LLM 模型配置指南

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：deploy/config/providers.toml、crates/cheng-nodes/src/nodes/builtin/ai/llm、deploy/.env.example

模型供应商在每套安装中配置一次，之后按节点选用。本文介绍供应商白名单、各供应商实际具备的能力，以及凭证如何挂接。

模型配置的三个层次

分三层，搞清楚你在改哪一层很有帮助：

1. deploy/config/providers.toml——供应商白名单。未在此注册的供应商根本无法使用。它声明凭证结构、能力和默认模型列表。
2. 凭证——你的密钥和端点，加密存放在凭证库中，每个供应商账号一条。
3. 节点配置——某个 ai/llm 或智能体节点使用哪个供应商和模型，在属性面板中选择。

已注册的供应商

共有十六个供应商预先注册。能力列反映的是平台实际会使用的能力，这并不总等同于厂商 API 所支持的能力：

在构建智能体之前，有两项值得特别注意。 Anthropic 和 Ollama 未声明原生 function calling——当前的供应商实现没有编码 tools 与 JSON mode，因此这项能力被刻意不予声明。如果你要构建 use_function_calling = true 的 ReAct 智能体，请从 ✅ 那一列中选择供应商。Anthropic 和 Ollama 用作普通 ai/llm 对话节点依然很好；这是工具调用方面的限制，不是对模型质量的评价。

Cohere 和 Jina 只提供向量嵌入/重排序——它们不会出现在对话模型下拉列表中，这是正确行为而非缺陷。

协议族

供应商按传输协议分组，这也是能支持这么多供应商的原因：大多数都使用 OpenAI 的 chat-completions 格式。

添加供应商凭证

在管理控制台中为供应商添加凭证。表单由该供应商声明的 credential_schema 生成，因此界面上恰好只显示这个供应商需要的字段：

敏感字段在界面中掩码显示，在 API 响应中脱敏。

模型列表

带 fetch_models_enabled 的供应商在配置好凭证后会从其 API 实时拉取模型列表——因此新模型无需更新 ChengOS 就会出现。当实时拉取不可用时，会使用 providers.toml 中声明的 default_chat_models 和 default_embedding_models。

上下文窗口与按模型覆盖

每个供应商都声明一个默认上下文窗口，并对不同的模型提供按模式匹配的覆盖。OpenAI 的默认值是 128K，但 gpt-3.5-turbo* 被覆盖为 16385——因为错误的上下文窗口要么浪费容量，要么导致请求因长度而失败。

覆盖项还为媒体模型声明输出模态：gpt-image-* 和 dall-e-* 输出图像，tts-* 输出音频。这正是媒体生成能够正确路由和校验的依据。

Anthropic 的 Claude 3.x/3.5 系列声明为 200K。

自托管与私有端点

Ollama、LM Studio 和 vLLM 只需端点、不需密钥。若模型服务位于私有地址，你还需要：

ALLOW_PRIVATE_LLM_ENDPOINTS=true

它默认为 true。设为 false 可阻止对私有网段的请求——在面向公网的安装上值得这么做，因为一个指向内网地址的工作流会变成 SSRF 攻击面。

其他任何使用 OpenAI 格式的服务都可以用 custom 供应商接入。

在节点上选择模型

使用 llm-model-select 控件的字段会显示一个跨所有已连接供应商的统一下拉列表。节点作者用 x-model-type、x-model-name-includes、x-model-name-excludes 和 x-provider-filter 收窄它——这就是为什么向量嵌入字段提供的是嵌入模型而非全部模型。

ai/llm 与智能体节点上的模型配置也可以通过 llm_config 以 JSON 对象形式提供，这是让工作流参数化模型（而非写死）的方式。

预设

deploy/config/presets.yaml 为节点类型定义具名的配置补丁——一个会被浅合并进目标节点配置的 config_patch。预设声明所属的 preset_type 分类、适用的 node_type、标签、可选的 risk_level（low、medium、high），以及 llm_visible（控制受限的 LLM 发现是否可以呈现该预设）。llm_visible 默认为 false，因此除非你显式开启，预设对模型是不可见的。

按工作区的 presets.yaml 会覆盖同 id 的全局预设（不区分大小写），也可以新增预设。

下一步

• 环境变量参考——相关配置项。
• 节点配置——模型选择控件。
• ReAct 智能体指南——工具调用支持在哪里起作用。