第 2 章大模型接入与使用 on 《从零学AI指南手册》

2.1 SDK 介绍

Mon, 01 Jan 0001 00:00:00 +0000

第 2 章大模型接入与使用#

2.1 SDK 介绍#

为了能更好地理解后续基于 LangChain 框架进行 RAG 大模型应用及 Agent 开发，这里我们先来介绍一下铺垫内容。

在日常开发中，我们经常会写出类似这样的代码 wechat.login()，虽然看起来再普通不过，但任何有过实战经验的开发者都知道：“登录”这件事，本身一点都不简单。那为什么 SDK 能把一个复杂的流程压缩成一个方法调用？要回答这个问题，我们必须先真正理解什么是 API，什么是 SDK。

2.1.1 API 是能力点#

从工程角度看，API 本质上是一个能力接口。比如在微信登录体系中，可能会存在这样的原生接口：

/oauth/authorize：负责授权
/oauth/access_token：负责获取登陆令牌
/oauth/refresh_token：负责获取刷新令牌
/userinfo：负责拉取用户信息

这些接口各自职责明确，每一个 API 都是一个原子能力点，它们的特点是足够底层、功能单一、调用成本高（参数多、约束多）。所以， API 的设计目标就是，我把能力开放给你，至于怎么用，那是你的事。

2.1.2 SDK是能力流#

软件开发工具包（Software Development Kit, SDK）的出现，本质上是为了解决一个现实问题，即下游开发者不想、也不应该，每次都从零开放一个完整流程。

例如，如果每个微信小程序的开发人员都要写一套微信登录流程，那不仅繁杂、工作量大，且实现方式也会五花八门，这既提高了微信应用开发的门槛，也不利于微信平台自身的管理和风险控制。

于是，SDK 做了一件非常重要的事情：把多个 API 和通用业务逻辑封装成一个可复用的工具包，这也是为什么 SDK 往往以类和方法的形式出现。

因此，开发者在开发面向微信应用的时候，表面上我们看到的是 user = wechat.login()，但在 SDK 内部可能已经完成了如下整套流程的实现：

① 参数与环境校验：appid 是否配置、redirect_url 是否合法、当前环境是否支持登录；

② 鉴权与安全处理：构造签名参数、防止重放攻击；

③ 调用底层 API：发起 /oauth/authorize 使用 refresh_token 获取取 access_token；

④ 结果校验与解析：校验返回签名、判断错误码、解析令牌与有效期；

2.2 现代大模型中的 SDK

Mon, 01 Jan 0001 00:00:00 +0000

2.2 现代大模型中的 SDK#

在传统 Web 开发中，很多开发者是直接调 API的，例如自己拼 HTTP 请求、自己处理鉴权、自己解析 JSON等等。但在大模型场景下，这种方式很快会失控，因为你面对的不再是一个增删改查接口，而是高并发推理服务、长文本输入输出、流式生成等等。

2.2.1 SDK 的重要性#

如果说早期 SDK 的目标是让 API 更好用，那么在大模型中 SDK 的目标就是让复杂系统看起来像一个本地对象一样，这也是非常典型的现代 SDK 设计范式。

以 OpenAI SDK 为例，我们来看一段典型的 SDK 使用方式，即把模型调用变成对象方法：

1 from openai import OpenAI
2 client = OpenAI(api_key="YOUR_API_KEY")
3 response = client.responses.create(model="gpt-4.1", i
4             nput="请用通俗的语言解释什么是 RAG", 
5             max_output_tokens=300, temperature=0.7)
6 print(response.output_text)

在上述代码中，第2行从表面看是实例化一个 OpenAI 客户端对象，但在 SDK 设计视角下它远不只是一个普通对象。

2.2.2 平台鉴权#

实际上 OpenAI(api_key="YOUR_API_KEY") 完成了 4 件关键的事情：

① 绑定平台身份：OpenAI() 会读取 OPENAI_API_KEY、构造鉴权信息，也就是说实例化类对象 client 是你在 OpenAI 平台上的身份代理。

② 确定一次能力边界：这个 client 对象，隐含了你是谁、你能用哪些模型、你的配额限流计费规则。

③ 初始化底层通信能力：SDK 内部通常会准备 HTTP 会话、超时策略、重试策略、代理配置等。

2.3 DashScope 接口体系

Mon, 01 Jan 0001 00:00:00 +0000

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.4 千问大模型接入与使用

Mon, 01 Jan 0001 00:00:00 +0000

2.4 千问大模型接入与使用#

上一节介绍了阿里云百炼、DashScope 与通义千问之间的关系。本节将进一步说明如何在阿里云百炼平台中准备模型调用环境，并分别通过 DashScope 原生 SDK、OpenAI 兼容模式以及 LangChain 相关组件调用千问系列模型。

2.4.1 阿里云百炼模型服务#

首先进入阿里云百炼官网（https://bailian.console.aliyun.com/ ），可以通过支付宝或淘宝扫码登录。登录成功后，在页面左上角选择“模型服务”，即可进入如图 2-4 所示的模型服务页面。

图 2-4. 阿里云百炼官网

进一步点击左侧的“模型用量”菜单，可以查看当前账号下可用的模型及其用量信息，包括大语言模型、视觉模型、全模态模型等。对于每个模型的具体能力，可以在左侧“模型体验”入口中进行试用和了解。

如图 2-5 所示，部分模型会提供测试额度。后续示例主要用于学习和开发验证，建议优先使用带有免费测试额度的模型，并在控制台中开启“免费额度用完即停”或类似的用量控制选项，以降低误调用带来的计费风险。

图 2-5. 模型总览

在实际开发中，还应定期通过控制台中的用量统计功能查看模型调用量、Token 消耗和资源包使用情况。对于生产环境，应结合业务规模设置更严格的预算、告警和权限管理策略。

2.4.2 创建并配置 API Key#

为了在代码中调用阿里云百炼平台中的模型，需要先创建 API Key。进入百炼控制台后，可以按照图 2-6 所示路径进入 API Key 管理页面。

图 2-6. 密钥创建步骤（一）

点击“创建 API Key”后，将进入如图 2-7 所示页面。

图 2-7. 密钥创建步骤（二）

确认创建后，即可在列表中看到如图 2-8 所示的 API Key。该密钥将作为后续代码访问百炼平台的身份凭证。

图 2-8. 密钥创建步骤（三）

在示例代码中，可以通过如下方式将 API Key 写入环境变量：

1 os.environ['DASHSCOPE_API_KEY'] = "YOUR_DASHSCOPE_API_KEY"

不过，在真实项目中不建议将密钥明文写入代码文件。更常见的做法是将密钥配置到操作系统环境变量、.env 文件或专门的密钥管理服务中，再由程序运行时读取。例如，在 Linux 或 macOS 终端中，可以将环境变量追加到 ~/.bashrc 或 ~/.zshrc 文件中：

第 2 章 大模型接入与使用 on 《从零学AI指南手册》

2.1 SDK 介绍

第 2 章 大模型接入与使用#

2.1 SDK 介绍#

2.1.1 API 是能力点#

2.1.2 SDK是能力流#

2.2 现代大模型中的 SDK

2.2 现代大模型中的 SDK#

2.2.1 SDK 的重要性#

2.2.2 平台鉴权#

2.3 DashScope 接口体系

2.3 DashScope 接口体系#

2.3.1 阿里云百炼与DashScope#

2.3.2 DashScope 支持的模型能力#

2.4 千问大模型接入与使用

2.4 千问大模型接入与使用#

2.4.1 阿里云百炼模型服务#

2.4.2 创建并配置 API Key#

第 2 章大模型接入与使用 on 《从零学AI指南手册》

第 2 章大模型接入与使用#