配置模型
Yuxi 在「智能体 → 模型供应商」中统一管理聊天、嵌入和重排模型。只有管理员可以新增或修改供应商；普通用户可以在有权限的地方选择已经启用的模型。读完本页，你能完成一次供应商接入并把模型投入实际使用，也能定位「模型不可用」的常见原因。
系统有一个默认对话模型（当前内置为硅基流动 siliconflow-cn:deepseek-ai/DeepSeek-V4-Flash，安装时可调整）。它同时也是删除操作的保护对象：Web 管理页面会在系统默认模型仍引用某个供应商或模型时阻止删除或停用。因此接入新模型前，先弄清当前默认模型指向哪里；替换或停用它之前，先把默认模型切换到别的模型。
配置顺序
- 打开「智能体 → 模型供应商」。
- 新增供应商，或打开一个内置供应商。
- 填写 API 地址和凭证，选择供应商能力。
- 在供应商的「模型配置」中获取远程模型，或手动添加模型。
- 对模型执行连接测试，再把它选为智能体或知识库使用的模型。
供应商停用后，其模型不会进入运行时模型缓存。直接调用管理 API 删除或停用供应商时，页面保护不生效，需要先自行检查并替换默认模型引用。
凭证怎么保存
供应商支持两种凭证来源：环境变量适合生产环境，页面直接填写适合本地测试。使用环境变量时，在供应商的「API Key Env」字段填写变量名（例如 SILICONFLOW_API_KEY），密钥本身放在 API/worker 容器环境中，不落数据库；直接填写的凭证保存在数据库中，只应在明确接受这个代价的环境使用。
修改容器环境变量后需要重新创建读取它的 API 和 worker，供应商页面的保存不会替你更新容器：
docker compose up -d --force-recreate api worker内置供应商
系统启动时会同步内置供应商模板。模板提供供应商 ID、API 地址、凭证变量名和模型发现地址；是否可用取决于凭证、供应商状态和已启用模型。页面列出的内容是当前实例的实际配置，完整模板由 builtin.py 维护。
| 展示名称 | Provider ID | 常见类型 | 凭证环境变量 |
|---|---|---|---|
| OpenAI | openai | chat | OPENAI_API_KEY |
| DeepSeek | deepseek | chat | DEEPSEEK_API_KEY |
| DashScope（中国站） | alibaba-cn | chat、embedding、rerank | DASHSCOPE_API_KEY |
| DashScope（国际站） | alibaba | chat | DASHSCOPE_API_KEY |
| Aliyun Coding Plan（中国站） | alibaba-coding-plan-cn | chat | DASHSCOPE_API_KEY |
| Aliyun Coding Plan（国际站） | alibaba-coding-plan | chat | DASHSCOPE_API_KEY |
| Zhipu（BigModel） | zhipuai | chat | ZHIPUAI_API_KEY |
| Zhipu Coding Plan（BigModel） | zhipuai-coding-plan | chat | ZHIPUAI_API_KEY |
| Zhipu（Z.AI） | zai | chat | ZAI_API_KEY |
| Zhipu Coding Plan（Z.AI） | zai-coding-plan | chat | ZAI_API_KEY |
| XiaomiMiMo Token Plan | xiaomi-token-plan-cn | chat | XIAOMI_MIMO_TOKEN_PLAN_API_KEY |
| XiaomiMiMo | xiaomi | chat | XIAOMI_MIMO_API_KEY |
| Kimi Code | kimi-for-coding | chat | KIMI_CODE_API_KEY |
| Moonshot（中国站） | moonshotai-cn | chat | MOONSHOT_API_KEY |
| Moonshot（国际站） | moonshotai | chat | MOONSHOT_API_KEY |
| MiniMax（中国站） | minimax-cn | chat | MINIMAX_API_KEY |
| MiniMax（国际站） | minimax | chat | MINIMAX_API_KEY |
| OpenRouter | openrouter | chat、embedding | OPENROUTER_API_KEY |
| ModelScope | modelscope | chat | MODELSCOPE_ACCESS_TOKEN |
| OpenCode | opencode | chat | OPENCODE_API_KEY |
| OpenCode Go | opencode-go | chat | OPENCODE_GO_API_KEY |
| SiliconFlow（中国站） | siliconflow-cn | chat、embedding、rerank | SILICONFLOW_API_KEY |
| SiliconFlow（国际站） | siliconflow | chat、embedding、rerank | SILICONFLOW_GLOBAL_API_KEY |
表中「常见类型」是模板预置或当前常见用途；模型仍需在供应商中启用，实际可用性以当前实例配置和供应商接口为准。alibaba-cn、openrouter、siliconflow-cn 和 siliconflow 的模板明确包含嵌入或重排能力，其他供应商能否添加某类模型取决于当前供应商配置的能力和接口。不要把 alibaba 和 alibaba-cn 混用：前者是 DashScope 国际站模板，后者带有内置的嵌入和重排配置。
添加和启用模型
从远程列表添加
打开供应商的模型配置，点击「获取远程模型」，从返回列表中选择模型。远程列表只用于发现候选项，不会自动启用模型；确认添加后，模型才会进入运行时。
手动添加
点击「手动添加」，填写模型 ID 和类型：chat 用于聊天和智能体运行；embedding 用于知识库向量化，需要填写供应商规格中的向量维度；rerank 用于对检索候选结果重排。
知识库创建后，嵌入模型和向量维度属于索引的一部分。更换嵌入模型或维度后，需要按知识库流程重建索引，不能把不同向量空间的结果混在一起。
模型标识
运行时使用 provider_id:model_id，只按第一个冒号分隔供应商和模型 ID。模型 ID 可以包含斜杠，例如：
siliconflow-cn:Pro/BAAI/bge-m3页面中的模型选择器会显示供应商名称和模型名称；在 API、日志或配置快照中排查问题时，使用完整 spec。
配置聊天模型的请求参数
OpenAI Completions API 兼容供应商的 chat 模型可以配置「模型请求参数 JSON」。Yuxi 会把它作为 OpenAI SDK 的 extra_body 合并到请求体顶层，用于支持不同供应商的思考或推理参数。
当前允许的顶层字段是：
| 字段 | 常见用途 |
|---|---|
enable_thinking | 开关式思考配置 |
thinking_budget | 思考 Token 预算 |
thinking | 供应商的思考配置对象 |
reasoning | 推理配置对象 |
reasoning_effort | OpenAI 风格的推理强度 |
示例：
{
"enable_thinking": true,
"thinking_budget": 1024
}白名单只限制顶层字段，字段内部结构和可用取值由供应商校验。参数是否生效取决于模型和供应商接口，Yuxi 不会把不支持的字段转换成另一种格式。Anthropic、Gemini 等非 OpenAI 兼容供应商不能使用这组 extra_body 覆盖。
按用户统计模型用量
如果需要在外部网关按用户计量模型用量，可以在供应商表单中打开「请求携带用户 ID」：开启后，该供应商的聊天模型请求会携带带 HMAC 签名的 x-yuxi-uid 请求头，网关验签后即可把用量归属到具体用户。开关默认关闭，需要先配置专用签名密钥 YUXI_UID_SIGNATURE_SECRET；协议细节、验签示例与安全边界见按用户统计模型用量。
更换或移除模型
在供应商的已启用模型列表中移除模型。Web 页面不会让当前默认模型直接移除，先在系统配置中换用其他模型再操作；直接调用管理 API 时需要自行保证默认引用仍然有效。知识库的嵌入模型变更后，按知识库页面重新建立索引。
旧版 provider/model、旧知识库 JSON 模型字段以及配置文件中的 model_names、embed_model_names、reranker_names 不属于当前运行时来源。升级后如果历史 Agent 或知识库仍保存旧格式，请在界面重新选择模型并保存；知识库嵌入模型变更后还要重建索引。
Ollama
当前版本没有 Ollama provider 类型，也没有 Ollama embedding 运行时适配。已有 Ollama embedding 知识库需要选择新的嵌入模型并重建索引。
排查模型不可用
按下面顺序检查：
- 供应商是否启用，模型是否位于「已启用模型」列表。
- API 地址是否能从 API/worker 容器访问。
- API Key Env 对应的变量是否存在，或直接凭证是否正确。
- 模型类型、嵌入维度和供应商能力是否匹配。
- 在供应商详情中执行连接测试，并查看 API/worker 日志中的错误。
模型连接测试能证明该次请求得到响应，不能证明所有模型参数、工具调用或知识库索引都适配；这些行为仍需在实际 Agent 或知识库链路中验证。