内容纲要
第 2 章：Models
来源：LangChain 文档导航 > Core components > Agents
链接：https://docs.langchain.com/oss/python/langchain/agents
大模型是 Agent的推理引擎，负责理解需求、调用工具、生成结构化或多模态输出，直接影响体验、成本与合规。除了常见的文本生成，大模型还支持工具调用、结构化数据、多模态、推理等。模型的质量会直接影响Agent的可靠性和性能。
大模型的使用常见两种方式，一种是在Agent内使用，还有一种是直接调用脱离于Agent相关框架。Langchian针对不同的大模型抽象了统一的方法<code>init_chat_model</code>初始化。
二、参数和调用
参数
大模型会根据接收的参数配置其能力，虽然大模型的参数可能存在差异，但大部分是一致的。以下参数也往往会出现在产品需求文档中，用于针对特定场景约定对大模型的调用。
| 分类 | 参数名 | 核心作用 | 说明与示例 |
|---|---|---|---|
| 基础身份与认证 | <code>**model**</code> | 指定使用的具体模型名称 / 标识符，关联模型提供商的特定模型版本 | 示例：<code>"gpt-4.1"</code>（OpenAI）、<code>"claude-sonnet-4-5-20250929"</code>（Anthropic）、<code>"gemini-pro"</code>（Google） |
| 基础身份与认证 | <code>**api_key**</code> | 模型提供商的身份验证密钥，用于访问 API | 通常通过环境变量（如 <code>os.environ["OPENAI_API_KEY"]</code>）设置，避免硬编码；部分本地模型无需此参数 |
| 基础身份与认证 | <code>model_provider</code> | 指定模型提供商，用于 <code>init_chat_model</code> 快速初始化不同厂商的模型 | 示例：<code>"openai"</code>、<code>"anthropic"</code>、<code>"azure"</code>、<code>"bedrock"</code>，配合 <code>model</code> 参数确定具体模型 |
| 输出控制 | <code>**temperature**</code> | 控制输出随机性：值越高（如 <code>1.0</code>）输出越创意多样，值越低（如 <code>0.1</code>）输出越确定保守 | 适合创意写作（<code>temperature=0.9</code>）、事实问答（<code>temperature=0.2</code>） |
| 输出控制 | <code>**max_tokens**</code> | 限制输出总 tokens 数，防止输出过长导致成本过高或超出模型能力 | 示例：<code>max_tokens=1000</code>，确保回答（含输入 + 输出）不超过 1000 个 tokens |
| 输出控制 | <code>logprobs</code> | 控制是否返回 token 级别概率值，用于分析模型对输出 token 的置信度 | 仅部分模型支持（如 OpenAI GPT-4o），需通过 <code>bind(logprobs=True)</code> 启用，可校验输出可信度 |
| 输出控制 | <code>structured_output</code> | 强制模型输出遵循指定格式（Pydantic/TypedDict/JSON Schema），便于后续解析 | 通过 <code>model.with_structured_output(MySchema)</code> 绑定，示例：指定 <code>Movie</code> 类（含 <code>title</code>/<code>year</code> 字段），模型输出自动匹配结构 |
| 请求控制 | <code>timeout</code> | 设定请求超时时间，超时后取消请求，避免无限等待 | 示例：<code>timeout=30</code>，30 秒内未收到响应则终止请求，适配网络不稳定场景 |
| 请求控制 | <code>max_retries</code> | 设定请求失败后的重试次数，应对网络波动、临时限流等问题 | 示例：<code>max_retries=2</code>，请求失败后重试 2 次，提升成功率 |
| 请求控制 | <code>max_concurrency</code> | 控制 <code>batch()</code>/<code>batch_as_completed()</code> 并行请求数，避免触发限流 | 通过 <code>config={"max_concurrency":5}</code> 设置，示例：同时处理 5 个并行请求 |
| 请求控制 | <code>rate_limiter</code> | 限制单位时间内请求数，主动规避模型提供商限流规则 | 示例：<code>InMemoryRateLimiter(requests_per_second=0.1)</code>（每秒最多 0.1 个请求，即 10 秒 1 次） |
| 网络与环境配置 | <code>base_url</code> | 自定义模型 API 基础地址，适配第三方兼容服务（如 vLLM、Together AI）或私有部署 | 示例：<code>base_url="https://api.together.xyz/v1"</code>，使用 Together AI 的 OpenAI 兼容 API |
| 网络与环境配置 | <code>proxy</code>/<code>openai_proxy</code> | 为请求设置 HTTP 代理，适配内网环境或需代理访问的场景 | 示例：<code>openai_proxy="http://proxy.example.com:8080"</code>（仅部分模型如 <code>ChatOpenAI</code> 支持） |
| 工具调用与高级功能 | <code>tools</code>/<code>bind_tools</code> | 为模型绑定可调用外部工具（如查天气、搜新闻），让模型主动触发工具执行 | 通过 <code>model.bind_tools([get_weather_tool])</code> 绑定，示例：绑定 <code>get_weather</code> 工具后，模型可生成 <code>get_weather(location="Boston")</code> 调用指令 |
| 工具调用与高级功能 | <code>tool_choice</code> | 强制模型调用工具：<code>"any"</code>（调用任意绑定工具）、具体工具名（如 <code>"get_weather"</code>） | 示例：<code>tool_choice="get_weather"</code>，确保模型必须调用天气查询工具 |
| 工具调用与高级功能 | <code>parallel_tool_calls</code> | 控制工具调用是否并行：<code>True</code> 可同时调用多个工具，<code>False</code> 需串行调用 | 示例：<code>parallel_tool_calls=False</code>，强制模型逐个调用工具，适合依赖前序结果的场景 |
| 工具调用与高级功能 | <code>multimodal</code> | 让模型处理 / 输出非文本数据（如图片、音频） | 输入示例：传递含 <code>{"type": "image", "base64": "..."}</code> 的 content block；输出示例：模型返回含图片 base64 的 <code>AIMessage</code> |
| 调用配置（Invocation Config） | <code>run_name</code> | 为当前调用命名，便于日志和追踪（如 LangSmith 调试） | 示例：<code>config={"run_name": "joke_generation"}</code>，标记该调用为 “生成笑话” |
| 调用配置（Invocation Config） | <code>tags</code> | 为调用添加标签，用于分类筛选（如按任务类型、用户群体） | 示例：<code>config={"tags": ["humor", "demo"]}</code>，标记为 “幽默”“演示” 类调用 |
| 调用配置（Invocation Config） | <code>metadata</code> | 附加自定义元数据（如用户 ID、请求 ID），用于关联业务上下文 | 示例：<code>config={"metadata": {"user_id": "123"}}</code>，绑定用户 ID 便于后续分析 |
| 调用配置（Invocation Config） | <code>callbacks</code> | 绑定回调函数，监听调用过程中的事件（如 token 生成、工具调用） | 示例：<code>config={"callbacks": [UsageMetadataCallbackHandler()]}</code>，追踪 token 使用量 |
| 调用配置（Invocation Config） | <code>recursion_limit</code> | 限制链（Chain）的递归深度，防止无限循环（如复杂多步推理场景） | 示例：<code>config={"recursion_limit": 10}</code>，限制最大递归 10 层 |
| 其他 | <code>prompt_cache_key</code> | 手动指定缓存键，显式触发 prompt 缓存（减少重复请求成本） | 仅部分提供商支持（如 OpenAI、Anthropic），示例：<code>prompt_cache_key="weather_boston_202411"</code>，复用历史请求结果 |
| 其他 | <code>configurable_fields</code> | 定义模型可配置字段（如 <code>model</code>、<code>temperature</code>），支持运行时动态修改 | 示例：<code>configurable_fields=("model", "temperature")</code>，后续可通过 <code>config={"configurable": {"model": "claude-sonnet"}}</code> 动态切换模型 |
调用
常见的调用方法有三类：
- Invoke：以消息方式作为输入，生成完成响应后对外输出；通过提供对话历史，来补充上下文，每条消息都会有一个角色，如<code>system</code>、<code>user</code>、<code>assistant</code>。
- Stream：流式输出，当于返回chunk时即展示。流式返回时候不是一个个字符的反馈，而是chunk块，代码中通过循环去处理这些chunk并在最终文档输出时候进行拼接。这里面，对于工具的调用输出也可以使用流式返回。
- Batch：批量处理，成批次请求，成批次返回；如果希望在每个单独的输入完成生成时就收到其输出，可以使用 <code>batch_as_completed()</code> 来流式传输结果。
大模型能力
工具调用 Tool Calling
模型可以请求调用工具来执行任务，例如从数据库中获取数据、搜索网页或运行代码。工具的详细定义会在第三章节进行说明，可以简单理解是 Schema 和 函数的结合体。Schema代表其类似元数据，包含了工具名称、使用描述、参与定义等，通常会是json的模式。
工具的使用可以使绑定方式进行 <code>bind_tools</code>，也可以交由大模型自行自主选择。对工具的调用可以强制指定某个工具，也可以是并行使用、循环使用。
结构化输出
代码中可以要求模型按照给定的模式提供响应。这有助于确保输出能够轻松解析并用于后续处理。该部分也将在第七章节进行说明。通常会约定输出为json结构，便于后续的代码逻辑处理。
扩展知识
多模态Multimodal
某些模型可以处理并返回图像、音频和视频等非文本数据可以通过提供内容块content blocks向模型传递非文本数据。该部分将在第三章节中说明，产品经理至少了解传入给大模型的文件、图片是通过什么方式提交的。
推理Reasoning
DeepSeek大火的时候是因为其推理能力让人一惊，在一些新的模型可以多步推理以得出结论，将复杂问题分解为更小、更易于处理的步骤。如果底层模型支持，你可以呈现这一推理过程，以更好地理解模型是如何得出最终答案的。推理的内容也支持流式输出，并且可以约定推理的层级。
提示词缓存 Prompt caching
提示词缓存可以减少重复处理相同令牌时的延迟和成本，比如在火山引擎中就支持直接在后台开启缓存机制。该缓存的开启也可以在代码中约定，详见上方的参数部分细节。
常见问题（FAQ）
- 供应商如何选？→ 先列任务对 Tool Calling/Structured Output 的要求，再比较上下文/延迟/价格，保留可切换机制。
- <code>invoke</code> vs <code>stream</code>？→ 前者适合后台审计，后者适合实时互动或语音。
- 批量会触发限流吗？→ 默认并发，需 <code>max_concurrency</code> + 队列/重试。
- 如何记录调用链？→ 用 <code>run_name</code>/<code>tags</code>/<code>metadata</code> 写业务 ID、渠道、实验组，配合 LangSmith。
- 可配置模型如何与工具共存？→ 先 <code>init_chat_model(temperature=0)</code>，再 <code>bind_tools</code>，运行时用 <code>configurable</code> 指定模型名。
- 如何追踪 token？→ <code>get_usage_metadata_callback()</code> 同时记录多模型用量。
- 如何避免递归死循环？→ 在复杂 Chain 中设置 <code>recursion_limit</code> 并用 callbacks 观察调用栈。
- Structured Output 会限制模型吗？→ 只需在需求中声明 schema，LangChain 会自动约束响应格式。
- 如何确保密钥安全？→ 将 API Key 放入环境变量或密钥管理工具，PRD 中需注明部署端的变量名。