Dify 源码解析 (二)：Model Runtime——如何优雅地统一百模千态

在上一篇源码解析中，我们宏观概览了 Dify 的架构。今天，我们将深入 Dify 的心脏地带：core/model_runtime。

随着 LLM（大语言模型）的爆发，我们正面临一个“百模大战”的时代。OpenAI、Anthropic、Google Gemini、Mistral 以及国内的文心一言、通义千问，再加上遍地开花的开源模型（Llama 3, Qwen 等），每个模型的 API 定义、参数结构、鉴权方式甚至 Token 计算规则都各不相同。

作为一款 LLM 应用开发平台，Dify 如何做到写一套代码，接入所有模型？答案就在 Model Runtime。

1. 核心架构：Adapter 模式的极致运用

core/model_runtime 的核心使命是抹平差异。它位于业务逻辑层（Application）和底层模型供应商（Model Providers）之间，充当了一个“通用翻译器”。

在代码结构上，该模块主要由以下几个部分组成：

Bash

core/model_runtime/
├── entities/          # 统一的数据实体（这是“普通话”）
├── errors/            # 统一的错误处理
├── model_providers/   # 各个模型厂商的具体实现（这是“方言翻译器”）
└── utils/             # 通用工具（如 Token 计算）

Dify 并没有简单地写一堆 if-else，而是采用了一种高度模块化的策略模式（Strategy Pattern）。

抽象基类的设计

虽然 Dify 是用 Python 编写的，但其设计思想非常具有面向对象的严谨性。所有的模型类型（LLM, Text Embedding, Speech2Text 等）都遵循一套严格的接口定义。

以 LLM 为例，核心抽象大致如下（简化示意）：

Python

class LargeLanguageModel:
    def invoke(self, model: str, credentials: dict, prompt_messages: list, ...) -> LLMResult:
        # 同步调用接口
        pass

    def stream_invoke(self, model: str, credentials: dict, prompt_messages: list, ...) -> Generator:
        # 流式调用接口
        pass

无论后端是调用 OpenAI 的 HTTP API，还是通过 HuggingFace 本地推理，对于上层业务来说，看到的永远只有 invoke 和 stream_invoke，以及统一的 LLMResult 返回对象。

2. 参数的统一：配置驱动（Configuration Driven）

不同的模型有不同的参数。例如 temperature 有的模型范围是 0-1，有的模型是 0-2；有的模型支持 top_p，有的支持 top_k。

Dify 如何处理这些差异？答案是 配置化。

在 model_providers 目录下，每个供应商（如 openai）都有一个 yaml 配置文件或对应的配置类。这个配置定义了该模型支持的所有参数及其规范。

动态映射机制

当业务层发起请求时，Runtime 会执行以下步骤：

1. 输入校验：根据配置文件的规则（如 min, max, required），验证前端传来的参数。

2. 参数转换：将 Dify 的标准参数名（如 max_tokens）映射为特定模型的参数名（例如某些模型可能叫 max_length）。

3. 默认值填充：如果用户未设置，则使用预设的最佳实践默认值。

这种设计使得增加新模型变得非常简单：往往只需要增加一个配置文件和少量的适配代码，而无需修改核心业务逻辑。

3. 消息格式的统一：Prompt Messages

这是最令人头疼的地方：

• OpenAI 格式：[{"role": "user", "content": "..."}]

• 某些开源模型：User: ... \n Assistant:

• Claude 旧版 API：\n\nHuman: ... \n\nAssistant:

Dify 定义了一套内部通用的消息实体 PromptMessage (位于 entities/message_entities.py)。

Python

class PromptMessage(BaseModel):
    role: str # user, assistant, system
    content: str | list[Content] # 支持多模态
    ...

在具体的 Provider 实现中（例如 core/model_runtime/model_providers/anthropic/llm/llm.py），会有一个转换函数，负责将 Dify 的 PromptMessage 列表“翻译”成该模型所需的具体 Prompt 字符串或 JSON 结构。

这带来的巨大优势是： 上层 Prompt Orchestration（提示词编排）模块完全不需要关心底层用的是什么模型，它只需要生成标准的 Message 对象即可。

4. Token 计费与预估：精打细算的艺术

对于商业化项目，Token 消耗就是金钱。Dify 在这里做了双重保障：

A. 预计算 (Pre-calculation)

在调用模型之前，Dify 需要知道这段 Prompt 大概会消耗多少 Token（用于限流或预判）。

model_runtime 内置了多种 Tokenizer。对于 OpenAI 兼容模型，使用 tiktoken；对于其他模型，如果没有提供专门的 Tokenizer，Dify 会使用近似估算算法或 HuggingFace 的通用 Tokenizer。

B. 真实消耗归一化 (Usage Normalization)

API 调用结束后，不同厂商返回的 Usage 格式五花八门。

• 有的在 Header 里。

• 有的在 Response Body 的 usage 字段。

• 有的（特别是流式响应）只在最后一个 Chunk 返回 Usage。

Dify 的 Runtime 层强制要求所有的 Provider 实现必须返回一个标准的 Usage 对象：

Python

class Usage(BaseModel):
    prompt_tokens: int
    completion_tokens: int
    total_tokens: int

特别亮点： 针对那些不返回 Usage 信息的本地模型或非标准 API，Dify 的 Runtime 会在接收到完整响应后，在服务端再次运行 Tokenizer 进行手动计算，填补 Usage 字段。这确保了无论模型多“简陋”，Dify 里的计费和统计数据永远是完整的。

总结：优雅的背后是标准

Dify 的 model_runtime 模块向我们展示了构建企业级 LLM 网关的最佳实践：

1. 面向接口编程：屏蔽底层实现细节。

2. 实体标准化：统一 Input (Prompt) 和 Output (Result/Usage)。

3. 配置大于编码：利用 Metadata 定义模型特性，降低扩展成本。

4. 兜底机制：在模型能力不足（如不返 Token 数）时，由 Runtime 层补齐能力。

正是这一层稳固的 Runtime，支撑起了 Dify 上层的工作流编排、RAG 检索和 Agent 智能，让开发者能够真正实现“一次编写，随意切换”。

---

下一步阅读建议

敬请期待下一篇：《Dify 源码解析 (三)：RAG 核心——索引、切片与检索链路的深度实现》。

---