自定义模型提供商

DeepAgents CLI 支持任意与 LangChain 兼容的聊天模型提供商，这意味着你可以使用几乎任何支持工具调用的 LLM。本文将详细介绍如何配置和使用各种模型提供商。

支持的模型提供商

DeepAgents 开箱即支持以下模型提供商：

提供商	软件包	API Key 环境变量	模型档案
OpenAI	`langchain-openai`	`OPENAI_API_KEY`	✅
Anthropic	`langchain-anthropic`	`ANTHROPIC_API_KEY`	✅
Google Gemini	`langchain-google-genai`	`GOOGLE_API_KEY`	✅
Google Vertex AI	`langchain-google-vertexai`	`GOOGLE_CLOUD_PROJECT`	✅
AWS Bedrock	`langchain-aws`	`AWS_ACCESS_KEY_ID`	✅
Ollama	`langchain-ollama`	可选	❌
Groq	`langchain-groq`	`GROQ_API_KEY`	✅
DeepSeek	`langchain-deepseek`	`DEEPSEEK_API_KEY`	✅
xAI	`langchain-xai`	`XAI_API_KEY`	✅
Fireworks	`langchain-fireworks`	`FIREWORKS_API_KEY`	✅
Perplexity	`langchain-perplexity`	`PPLX_API_KEY`	✅

模型档案：包含模型档案的提供商，其模型会自动出现在交互式 /model 切换器中。

DeepAgents 模型提供商生态全景

安装提供商软件包

每个模型提供商都需要安装对应的 LangChain 集成包：

bash

# 安装单个提供商
uv tool install 'deepagents-cli[anthropic]'

# 安装多个提供商
uv tool install 'deepagents-cli[anthropic,openai,groq]'

# 之后添加额外软件包
uv tool upgrade deepagents-cli --with langchain-ollama

# 安装所有提供商
uv tool install 'deepagents-cli[anthropic,bedrock,cohere,deepseek,fireworks,google-genai,groq,huggingface,ibm,mistralai,nvidia,ollama,openai,openrouter,perplexity,vertexai,xai]'

切换模型

方式一：交互式选择器

在会话中使用 /model 命令打开交互式选择器：

> /model

选择器会显示所有可用模型，按提供商分组。

方式二：直接指定

直接指定 provider:model 格式：

> /model openai:gpt-4o
> /model anthropic:claude-sonnet-4-5
> /model google_genai:gemini-2.5-pro

方式三：启动时指定

在命令行启动时指定模型：

bash

deepagents --model openai:gpt-4o
deepagents --model anthropic:claude-opus-4-5

三种模型切换方式对比

设置默认模型

设置持久化默认模型，用于未来所有启动：

通过命令

> /model --default anthropic:claude-sonnet-4-5

通过 shell

bash

deepagents --default-model anthropic:claude-opus-4-6

查看和清除默认值

bash

# 查看当前默认值
deepagents --default-model

# 清除默认值
deepagents --clear-default-model

# 或在会话中
> /model --default --clear

模型解析优先级

CLI 启动时按以下顺序解析模型：

--model 标志：始终优先生效
[models].default：config.toml 中的默认设置
[models].recent：最近一次使用的模型
环境变量自动检测：按 OPENAI_API_KEY → ANTHROPIC_API_KEY → GOOGLE_API_KEY → GOOGLE_CLOUD_PROJECT 顺序

模型解析四级优先级链

配置文件详解

创建 ~/.deepagents/config.toml 文件配置模型提供商：

基础配置结构

toml

# 默认模型设置
[models]
default = "anthropic:claude-sonnet-4-5"     # 持久化默认值
recent = "openai:gpt-4o"                    # 最近使用（自动写入）

# 提供商配置
[models.providers.<provider_name>]
models = ["model1", "model2"]               # 在选择器中显示的模型
api_key_env = "API_KEY_ENV_VAR"            # API Key 环境变量名
base_url = "https://api.example.com/v1"    # 自定义端点
class_path = "module.path:ClassName"        # 自定义类（任意提供商）

[models.providers.<provider_name>.params]
temperature = 0                             # 模型参数
max_tokens = 4096

配置键说明

键	类型	说明
`models`	string[]	在交互式选择器中显示的模型列表
`api_key_env`	string	覆盖用于检查凭据的环境变量名
`base_url`	string	覆盖提供商的 base URL
`class_path`	string	自定义 BaseChatModel 子类的路径
`params`	object	传给模型构造函数的额外参数

config.toml 配置文件结构解剖

配置示例

配置 Ollama 本地模型

toml

[models.providers.ollama]
models = ["llama3", "mistral", "codellama", "qwen3:4b"]
base_url = "http://localhost:11434"

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

使用：

bash

deepagents --model ollama:llama3

按模型覆盖参数

toml

[models.providers.ollama]
models = ["qwen3:4b", "llama3"]

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

# qwen3:4b 使用不同参数
[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5
num_ctx = 4000

合并规则：

ollama:qwen3:4b → {temperature: 0.5, num_ctx: 4000}
ollama:llama3 → {temperature: 0, num_ctx: 8192}

配置 Azure OpenAI

toml

[models.providers.azure]
class_path = "langchain_openai:AzureChatOpenAI"
api_key_env = "AZURE_OPENAI_API_KEY"
models = ["gpt-4", "gpt-4o"]

[models.providers.azure.params]
azure_endpoint = "https://my-resource.openai.azure.com"
api_version = "2024-02-15-preview"
deployment_name = "gpt-4"

使用 OpenAI 兼容 API

许多提供商暴露 OpenAI 兼容的 API，可以通过 base_url 直接使用：

toml

[models.providers.openai]
base_url = "https://api.example.com/v1"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-custom-model"]

使用 Anthropic 兼容 API

toml

[models.providers.anthropic]
base_url = "https://api.example.com"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-model"]

四种配置模式对比

任意提供商配置

通过 class_path 使用任意 LangChain BaseChatModel 子类：

toml

[models.providers.my_custom]
class_path = "my_package.models:MyChatModel"
api_key_env = "MY_API_KEY"
base_url = "https://my-endpoint.example.com"
models = ["my-model-v1", "my-model-v2"]

[models.providers.my_custom.params]
temperature = 0
max_tokens = 4096

安装自定义包：

bash

uv tool upgrade deepagents-cli --with my_package

使用：

bash

deepagents --model my_custom:my-model-v1

当切换到 my_custom:my-model-v1 时，CLI 会这样实例化：

python

MyChatModel(
    model="my-model-v1",
    base_url="https://my-endpoint.example.com",
    api_key="...",
    temperature=0,
    max_tokens=4096
)

class_path 自定义提供商实例化机制

命令行参数覆盖

使用 --model-params 做一次性参数调整：

bash

# 调整温度
deepagents --model ollama:llama3 --model-params '{"temperature": 0.9}'

# 调整上下文窗口
deepagents --model ollama:llama3 --model-params '{"num_ctx": 16384}'

# 非交互模式
deepagents -n "总结这个仓库" --model ollama:llama3 --model-params '{"temperature": 0}'

--model-params 优先级最高，会覆盖配置文件中的值。

参数覆盖三层优先级

添加模型到选择器

某些提供商（如 Ollama）不附带模型档案数据，其模型不会出现在 /model 选择器中。通过配置文件补齐：

toml

[models.providers.ollama]
models = ["llama3", "mistral", "codellama", "qwen3:4b"]

之后 /model 选择器会包含 Ollama 分组并列出这些模型。

即使不配置，你也可以直接指定模型名：

> /model ollama:llama3

完整配置示例

toml

# ~/.deepagents/config.toml

# 默认模型
[models]
default = "anthropic:claude-sonnet-4-5"

# Ollama 本地模型
[models.providers.ollama]
models = ["llama3", "qwen3:4b", "codellama"]
base_url = "http://localhost:11434"

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5

# Azure OpenAI
[models.providers.azure]
class_path = "langchain_openai:AzureChatOpenAI"
api_key_env = "AZURE_OPENAI_API_KEY"
models = ["gpt-4", "gpt-4o"]

[models.providers.azure.params]
azure_endpoint = "https://my-resource.openai.azure.com"
api_version = "2024-02-15-preview"

# OpenAI 兼容的自定义服务
[models.providers.my_llm]
base_url = "https://api.my-llm.com/v1"
api_key_env = "MY_LLM_API_KEY"
models = ["my-model-7b", "my-model-70b"]
class_path = "langchain_openai:ChatOpenAI"

[models.providers.my_llm.params]
temperature = 0.7

注意事项

模型支持工具调用：DeepAgents 依赖工具调用能力，确保选择的模型支持此功能
API 兼容性：使用兼容 API 时，提供商特有的功能可能无法使用
安全性：class_path 会执行配置文件中的 Python 代码，确保只使用可信的配置
环境隔离：自定义包必须安装在与 deepagents-cli 相同的 Python 环境中

小结

本文介绍了 DeepAgents 的模型提供商配置：

内置提供商：支持 OpenAI、Anthropic、Google、AWS 等主流提供商
模型切换：三种方式切换模型（选择器、直接指定、启动参数）
默认模型：设置持久化默认模型
配置文件：通过 config.toml 自定义提供商配置
本地模型：配置 Ollama 等本地模型
兼容 API：使用 OpenAI/Anthropic 兼容的第三方服务
任意提供商：通过 class_path 使用任意 LangChain 模型

至此，第七部分「进阶配置篇」完成。下一部分是项目实战篇，我们将通过四个完整项目演示如何综合运用 DeepAgents 的各项能力。

自定义模型提供商 ​

支持的模型提供商 ​

安装提供商软件包 ​

切换模型 ​

方式一：交互式选择器 ​

方式二：直接指定 ​

方式三：启动时指定 ​

设置默认模型 ​

通过命令 ​

通过 shell ​

查看和清除默认值 ​

模型解析优先级 ​

配置文件详解 ​

基础配置结构 ​

配置键说明 ​

配置示例 ​

配置 Ollama 本地模型 ​

按模型覆盖参数 ​

配置 Azure OpenAI ​

使用 OpenAI 兼容 API ​

使用 Anthropic 兼容 API ​

任意提供商配置 ​

命令行参数覆盖 ​

添加模型到选择器 ​

完整配置示例 ​

注意事项 ​

小结 ​

自定义模型提供商

支持的模型提供商

安装提供商软件包

切换模型

方式一：交互式选择器

方式二：直接指定

方式三：启动时指定

设置默认模型

通过命令

通过 shell

查看和清除默认值

模型解析优先级

配置文件详解

基础配置结构

配置键说明

配置示例

配置 Ollama 本地模型

按模型覆盖参数

配置 Azure OpenAI

使用 OpenAI 兼容 API

使用 Anthropic 兼容 API

任意提供商配置

命令行参数覆盖

添加模型到选择器

完整配置示例

注意事项

小结