2.3 DashScope 接口体系#

RAG 应用和 Agent 智能体虽然通常借助 LangChain、LangGraph 等框架完成流程编排，但其底层能力仍然来自具体的大模型服务。因此，在进入后续 RAG 开发之前，需要先明确模型平台、接口体系以及具体模型之间的关系。本书后续示例将以阿里云百炼平台中的通义千问系列模型作为主要模型能力来源。

2.3.1 阿里云百炼与DashScope#

在接入通义千问、词嵌入模型以及多模态模型时，开发者经常会遇到两个概念层面的问题：

① 通义千问与阿里云百炼是什么关系，DashScope 又承担什么角色？

② 为什么部分示例代码中没有显式导入 DashScope，却仍然能够调用通义千问模型？

阿里云百炼是阿里云面向开发者提供的大模型服务平台，开发者可以在该平台上开通模型、管理密钥、查看用量，并使用通义千问、Embedding、多模态等模型能力。DashScope 则是百炼平台向外提供模型能力的接口体系，包含 HTTP API、Python SDK 以及兼容 OpenAI 协议的调用方式。

从整体关系上看，可以将三者理解为：

阿里云百炼：大模型服务平台与产品入口；
DashScope：百炼平台对外暴露模型能力的 API 与 SDK 体系；
通义千问、Embedding、多模态模型：实际承载推理、向量化或多模态处理任务的模型能力。

通过图2-1所示，可以更直观地理解不同实体在整体架构中的位置。

图 2-1. DashScope 架构位置图

因此，DashScope 的核心职责是将阿里云百炼中的模型能力封装为稳定、统一、可编程、可升级的接口层。开发者并不是直接访问某一个模型服务实例，而是通过 DashScope 提供的接口规范完成鉴权、参数传递、模型调用、结果解析和错误处理。

2.3.2 DashScope 支持的模型能力#

DashScope 并不是某一个具体模型，而是面向多类模型能力的统一接口体系。凡是在阿里云百炼平台中开放给开发者使用的模型能力，通常都可以通过 DashScope 提供的接口进行调用。

图 2-2. 百炼平台产品

如图 2-2 所示，阿里云百炼平台提供了多种模型产品和相应的调用示例，覆盖文本生成、文本向量化、视觉理解、语音处理以及多模态等能力。在本书后续章节中，主要会使用两类与 RAG 应用直接相关的能力：

① 文本生成模型：用于对话、问答、摘要、推理和内容生成等任务；

② 词嵌入模型：用于将文本转换为向量表示，支撑后续的向量检索和语义匹配。

这两类模型分别对应 RAG 系统中的两个关键环节：一是通过 Embedding 模型完成文档和问题的向量化，二是通过 Chat 模型根据检索结果生成最终回答。因此，在掌握 DashScope 的接口体系之后，后续的 RAG 开发才能建立在清晰的模型调用基础之上。

2.3.3 ChatOpenAI中的 DashScope#

在实际开发中，经常可以看到如下代码：

1 from langchain_openai import ChatOpenAI
2 import os
3 
4 chatLLM = ChatOpenAI(
5     api_key=os.getenv("DASHSCOPE_API_KEY"),
6     base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
7     model="qwen-plus")

这段代码从表面看使用的是 LangChain 中的 ChatOpenAI，并没有出现 import dashscope。但从调用链路看，它仍然是在通过 DashScope 访问阿里云百炼中的通义千问模型。原因在于 DashScope 同时提供了两套接口体系：

① 原生 DashScope 接口：包括官方 SDK dashscope 以及对应的原生 HTTP API。该方式能够较完整地使用百炼平台提供的模型能力，新模型、新参数和平台特性通常会优先在原生接口中得到支持。

② OpenAI Compatible Mode（OpenAI 兼容模式）：请求格式与 OpenAI API 保持兼容，但实际的模型调用、鉴权、计费和用量统计仍然发生在阿里云百炼体系中。此时，开发者使用的是 OpenAI 风格的调用协议，但访问目标已经通过 base_url 指向了 DashScope 的兼容接口地址。

因此，是否显式导入 dashscope 并不是判断是否使用 DashScope 的唯一标准。只要请求地址指向 DashScope 的接口，且使用的是百炼平台的 API Key 与模型名称，本质上就是在通过 DashScope 调用阿里云百炼中的模型能力。

2.3.4 OpenAI 兼容模式#

在大模型应用发展的早期阶段，OpenAI 形成了较强的生态影响力。LangChain、LlamaIndex 以及大量开源项目都曾以 OpenAI 风格的接口作为默认调用方式，许多业务系统也已经围绕这一协议完成了封装。如果新的模型平台要求开发者完全改写调用方式，就会显著提高迁移门槛。因此，DashScope 提供 OpenAI 兼容模式来降低已有应用迁移到阿里云百炼体系时的工程成本。

例如，在 LangChain 的部分示例中，模型调用入口常常以 OpenAI 风格呈现。

图 2-3. LangChain 官方示例代码

在兼容模式下，开发者通常只需要调整两类配置：

- OPENAI_API_KEY
+ DASHSCOPE_API_KEY

- https://api.openai.com/v1
+ https://dashscope.aliyuncs.com/compatible-mode/v1

随后将模型名称替换为百炼平台中对应的模型，例如 qwen-plus，大部分上层代码即可保持不变。这种设计使得已有 OpenAI 风格项目能够以较低成本迁移到千问等模型上，也使 LangChain 等框架能够通过统一接口访问不同模型平台。

2.3.5 兼容模式选择#

在实际工程中，原生 DashScope 接口与 OpenAI 兼容模式并不存在绝对优劣，二者适用于不同场景。如果是新建项目，或者需要深度使用阿里云百炼提供的新模型、新参数、多模态能力、异步任务能力等平台特性，优先选择原生 DashScope 接口更为合适。原生接口的能力覆盖更完整，参数表达更直接，也更便于跟随百炼平台的新能力升级。

如果是从 OpenAI 风格项目迁移而来，或者项目中已经大量使用 ChatOpenAI、OpenAI SDK、LangChain OpenAI 适配器等组件，则可以优先选择 OpenAI 兼容模式。该方式的优势在于改动范围小，通常只需要替换 API Key、接口地址和模型名称，就可以完成基础模型的切换。

在本书后续示例中，将根据具体任务选择合适的接口方式。在需要体现百炼平台原生能力时，优先使用 DashScope；在需要与 LangChain 生态快速衔接时，则使用 OpenAI 兼容模式。理解这两种接口体系的边界，是后续正确接入千问模型和构建 RAG 应用的前提。