硅基边界模型层-自部署模型怎么接进来

自部署模型怎么接进来？三个框架接入实录

面向私有化部署与模型运维：讲清一套零代码 AI 智能体平台的模型层怎么配、自部署模型怎么接、以及哪些参数你以为能改其实改不了。

先说结论：接自部署模型只有一条硬要求——服务端必须暴露 OpenAI 兼容接口（/v1/chat/completions那一套规范）。满足它，vLLM、Ollama、Xinference 都能接；不满足，改再多配置也没用。

同时有三件事我先说在前面，因为它们比接入步骤更容易让人白折腾半天：

1. 平台里的「模型」配置分散在多个模块，作用范围完全不同，改错地方等于没改；
2. 通过 API 调用时，请求体里的model和temperature会被服务端忽略，参数以平台侧配置为准；
3. 供应商配置是全局的——改一次 API Base，所有引用它的模型一起生效。

下面按「先看全貌 → 再看协议 → 接入实录 → 边界与坑」的顺序展开。

一、先看全貌：模型配置分散在多个模块

很多人第一次找「换模型」的入口会在控制台里转好几圈，原因是这套平台的模型配置按作用域分散在不同模块，不是集中在一个「模型设置」页里。

表里前四行是可以选定模型的位置，最后一行不提供选择——这点在第二节单独展开。

这张表是本文最该先记住的东西。后面的坑基本都源于把某一层的作用范围记错了。

举两个常见误判：

• 在工作流大模型节点里把温度调成 0.1，然后去网页端对话发现语气还是很跳——因为节点级温度只影响这个节点，网页端对话走的是智能体配置里的温度。
• 想换数据库问答的模型，却跑到智能体模型配置里去改——智能体的模型配置影响的是对话主模型，而生成 SQL 的那次调用有它自己的模型入口。

二、内置模型与「不能选」的部分

2.1 内置大语言模型清单

官方文档明确列出目前支持的大语言模型：

智谱 AI | 豆包 | 深度求索 | 七牛云 | 通义千问 | CloseAI

官方对选型的提示很实在：不同模型的参数规模、训练方法各异，能力表现也不同。通常参数越大，模型理解提示词和推理的能力越强，但输出速度会相应变慢。建议按实际场景和成本考量选择。

模型管理页支持三个维度筛选：服务商、类型（文本生成、图像等）、来源（内置模型 / 自定义模型）。

来源这个维度要特别注意：

• 内置模型由平台维护，不支持编辑和删除；
• 自定义模型支持完整的编辑、删除操作（鼠标悬停卡片出现操作按钮）。

2.2 多模态能力不在模型模块里

这点容易让人找错地方。文生图、文生视频、图像识别这三类能力不在模型模块中作为「模型」出现，而是由插件提供：

使用方式是在智能体配置中开启对应插件，或在流程中通过插件节点调用。

实践结论：想换文生图模型，不是去模型模块加一个模型，而是先看目标插件提供哪些选项。这两条路不互通。

2.3 Embedding 模型：内置，无需选择

知识库内置向量化模型，用于把上传的文档嵌入向量库，并把用户提问向量化以匹配知识库内容。官方原文很直接：

该模型无需手动选择，系统已内置。

实践结论：向量化模型的选型不在用户可操作范围内。如果你的场景对 Embedding 有硬要求（比如必须用某个特定的多语言模型），这条需要提前向平台确认，而不是等接完知识库才发现改不了。

三、自定义模型：唯一硬要求是 OpenAI 协议

3.1 官方原文的措辞

平台仅支持 OpenAI 协议格式的接口接入。供应商的 API 必须兼容 OpenAI 的请求/响应格式（如/v1/chat/completions接口规范），否则无法正常调用。

注意「仅」这个字——它意味着不是「优先支持 OpenAI 协议」，而是只认这一种。如果你手上是个只提供自有协议的内网推理服务，中间必须加一层协议转换网关。

3.2 官方给出的三条兼容路径

一个值得注意的细节：Kimi 出现在这里，但不在内置大语言模型清单里（内置清单是智谱 AI、豆包、深度求索、七牛云、通义千问、CloseAI 六家）。也就是说，如果你要用 Kimi，走的是自定义模型的兼容接口这条路，而不是从内置列表里选。

这类「清单和路径不完全对应」的地方，建议以文档原文分页为准去核对，别按印象推断。

3.3 新增供应商：五个字段

官方关于 API Key 的三条安全提醒值得照做：

• API Key 是访问模型服务的核心凭证，请妥善保管；
• 提交后系统不再明文回显，编辑时留空表示保持原 Key 不变；
• 建议使用供应商提供的子账号 Key，按需配置最小权限。

第二条在运维上很关键：因为不回显，所以「忘了填就保存」不会把 Key 清空——这点比很多人预期的安全。

3.4 创建模型：六个字段

点「+自定义模型」按钮，先选供应商，再填模型信息：

选择供应商后，系统会自动填充该供应商的 API Base 与 API Key；如需修改可点「配置供应商」。

官方给了两条警告，都指向同一类问题：

模型名称须与供应商接口一致：调用时会作为model字段透传给供应商，填写错误会导致接口报错。

最大上下文须符合模型实际限制：超出模型原生容量会导致请求被供应商拒绝或内容被截断。

3.5 第一个大坑：模型名称不是「给自己看的备注」

「模型名称」这一栏出现在管理界面上，很容易被当成一个可读性标签——比如填成「生产环境 - Qwen - 主用」。这是错的。

它会被原样透传给供应商作为model字段。而自部署场景下，这个值必须和推理框架暴露出来的模型标识严格一致：

• vLLM 下是启动参数--served-model-name指定的名字；
• Ollama 下是名称:标签的形式（如qwen2.5:7b）；
• 调用云端厂商时是厂商文档里给的那个 model ID。

名字不一致的表现是接口报错，而不是「回退到默认模型」。所以接自部署模型时，第一件事是确认服务端暴露的标识到底叫什么，而不是照着 Hugging Face 仓库名填。

四、私有化接入实录：vLLM / Ollama / Xinference

这一节是纯工程落地。先说明：下面的启动命令是各推理框架官方文档的标准用法，与平台无关；本文要说清的是它们暴露出来的 OpenAI 兼容端点怎么对接到平台。

4.1 三个框架的定位差异

选哪个不影响接入方式——只要它暴露的是 OpenAI 兼容接口，平台这一侧看到的都一样。

4.2 三个框架怎么把兼容接口暴露出来

vLLM：

# 启动时指定 served-model-name，这个值就是后面要填进「模型名称」的东西vllm serve Qwen/Qwen2.5-7B-Instruct\--served-model-name qwen2.5-7b\--host0.0.0.0\--port8000# 暴露出来的 OpenAI 兼容端点# http://{内网IP}:8000/v1

Ollama：

# 拉起服务并准备模型ollama serve ollama pull qwen2.5:7b# 暴露出来的 OpenAI 兼容端点# http://{内网IP}:11434/v1# 模型标识：qwen2.5:7b

Xinference：

# 启动服务xinference-local--host0.0.0.0--port9997# 拉起一个模型（会返回模型 UID，后续调用用这个 UID 或模型名）xinference launch --model-name qwen2.5-instruct --model-format pytorch# 暴露出来的 OpenAI 兼容端点# http://{内网IP}:9997/v1

注意最后一行：三个框架的/v1前缀是接入时的关键。平台的「API Base」要填到/v1/这一层，而不是只填到端口。

4.3 接入前三步验证

官方在「接入第三方模型时请注意」里写了一条容易被忽略的要求：

私有化部署请确保服务地址在内网可达且稳定。

这句话在实操里要拆成三步验证，少一步都可能在平台上遇到「明明填对了却调不通」：

第一步：在推理服务器本机测通

curlhttp://127.0.0.1:8000/v1/chat/completions\-H'Content-Type: application/json'\-d'{ "model": "qwen2.5-7b", "messages": [{"role": "user", "content": "你好"}] }'

第二步：从平台侧能访问的网络里测通

把127.0.0.1换成服务器内网 IP，在与被调用的业务系统同网段的机器上再跑一次。这一步失败通常是防火墙、安全组或容器网络没放行，而不是平台的问题。

第三步：压一个长请求，确认链路稳定

官方要求里还有两个字是「稳定」。用一条长输入（比如带几百字上下文的请求）跑几次，看是否出现超时或截断。短请求能通、长请求被网关掐断，在自部署环境里并不少见。

4.4 填进平台

三步都通了，再回到模型模块配置：

关于 API Key 有一个实践惯例要讲清楚：多数自部署推理框架默认不校验 API Key，但平台这个字段是必填的，所以通常填一个占位字符串即可；如果你的推理服务前面挂了网关（如 OpenAI 兼容代理、各类 AI 网关），网关可能会真的校验 Key，这时就要填实际的值。

这条以你的部署为准——不要因为「vLLM 不校验」就假设整条链路不校验。

五、上下文：一条四层约束链

上下文长度是接入模型时最容易算错的东西，因为平台里有四层都在管它。任何一层算小了，表现都是「知识被截断、回答变差」，而且报错信息不会直接告诉你是哪一层。

智能体这一层，官方给了一个明确的构成公式：

上下文长度 = 保存的记忆轮次的问 & 答内容 + 智能体设定 + 本次提问知识库命中内容 + 本次用户问题 + 本次模型回复

知识库这一层，官方的提醒是：

可依据单条长度、检索返回条数，预估单次对话带入知识库内容总字符量，该总量不可超过模型配置的最大上下文长度，否则会截断知识内容、影响回答效果。

一个口径提示：公式里的「轮次问答」「用户问题」用的都是 Token，而知识库那一段官方用的是字符。这两者不是 1:1 的关系。所以做容量估算时，知识库部分要先按实际分词结果折算，再代入 Token 口径的公式——直接拿字符数当 Token 数相加，是最常见的估算错误。

实践结论：算上下文要从最窄的一层倒推。模型的最大上下文是天花板，但真正决定效果的是「记忆轮次 + 知识库命中量」这两项之和——它们才是你实际能控制、也最容易被调过头的部分。

六、温度与模型参数：在哪儿配才生效

6.1 先说最反直觉的一条

OpenAPI 的兼容性说明里写得很清楚：

请求体接受model、temperature等 OpenAI SDK 附带字段，但会被忽略——智能体使用自身配置的模型与参数。

官方的 SDK 示例里也带着注释：

fromopenaiimportOpenAI client=OpenAI(api_key="{api_key}",base_url="https://{host}/ai/open/v1/agent",# SDK 会自动拼接 /chat/completions)stream=client.chat.completions.create(model="agent_xxx",# SDK 必填字段,服务端忽略,可填 code 值messages=[{"role":"user","content":"你好"}],extra_body={"code":"agent_xxx"},# code 等自定义字段经 extra_body 传入stream=True,)

第一行注释就是答案：model是 SDK 的必填字段，所以你必须传，但服务端不看它，可以随便填成 code 值。

这条的工程后果：参数只在平台侧生效，客户端改不动。

6.2 温度的两个生效点

同一个模块里还有一项容易和温度混着调的配置——记忆轮次（0~50轮），管的是对话上下文保留多少轮，跟生成风格无关。两者建议分开调，一起动的话效果差异分不清是哪一项带来的。

官方还给了场景化的建议：知识库问答业务场景，温度建议上限0.3。

这条建议的适用范围值得展开一下——知识库问答要的是「照着语料答」，温度拉高会让模型开始自由发挥，命中率反而下降。而如果你的智能体更像是创意助手，那这个 0.3 就不适用。

6.3 一个架构层面的结论

把上面两条连起来看，会得到一个会影响接口设计的结论：

「同一个智能体，给 A 客户 0.1 的温度、给 B 客户 0.8 的温度」——在 API 层做不到。

因为temperature传进去会被忽略。要实现这种差异，只有两条路：

1. 在平台上建两个智能体，各自配好温度，调用方按code区分；
2. 把「按参数分叉」的逻辑做进工作流——不同分支走到不同的大模型节点，利用节点级温度实现。

同样地，这也解释了为什么 SDK 里那个model参数不能用来做模型切换：换模型必须回平台改配置。

七、响应里的 model 字段：一个成本归因的坑

这个坑很隐蔽，但在做用量统计时一定会撞上。

官方在「资源标识 code」一节写着：

智能体与工作流均通过唯一 code 码标识，填在请求的code参数中；响应里的model字段会原样回填该 code。

看响应示例就更清楚了：

{"id":"chatcmpl-xxxx","object":"chat.completion","created":1766649600,"model":"agent_xxx","choices":[{"index":0,"message":{"role":"assistant","content":"……"},"finish_reason":"stop"}],"usage":{"prompt_tokens":120,"completion_tokens":35,"total_tokens":155}}

"model": "agent_xxx"—— 这里回填的是code，不是你配置的模型名。

为什么这是个坑：按 OpenAI 的使用习惯，很多人会把响应里的model字段直接落库，用来做「哪个模型花了多少」的分组统计。在这套接口下，这个字段拿到的是 code，按它分组等于按智能体分组，不是按模型分组。

正确做法：日志里落code做归因，再在平台侧维护一份「code → 模型」的映射表。如果多个智能体共用同一个模型，那成本归因的粒度天然就止步于 code 这一层。

八、计费口径：两个单位不要混

模型详情页里有一节叫「计费与上下文（仅内置模型）」，包含两个字段：

计费规则（官方原文）：

• 平台按「单次请求的输入 Token 范围」分档计费；
• 不同档位对应不同的输入单价、输出单价；
• 实际费用 = （输入 Token × 输入单价） + （输出 Token × 输出单价）。

这里有两点必须说清，否则做成本预估时一定会算错：

第一，「仅内置模型」这四个字很重要。自定义模型的费用发生在你自己的供应商侧（自部署的算力成本、或云端厂商的账单），平台侧不展示它的单价。所以自部署接入的模型在平台账单里不会出现模型费这一项——这也是私有化场景下「模型成本可控」的原因。

第二，Token 单价是这里的分档展示口径，而平台账户侧的实际消耗单位是「粒子」。这个区分在知识库页能看得很直观：上传文档时，页面左下方会展示当前文件总 Token 数，并同步生成预估粒子；知识库的智能解析按15 粒子 / 页计费。

实践结论：与业务侧对账时用账户侧的「粒子」口径，做用量日志分析时用usage里的 Token 字段——这是两个不同层面的口径，不要混成一句话说。

九、五个最容易踩的兼容性边界

把全文的边界集中在这里，都是「你以为会生效、实际不会」的类型。

第一，供应商配置是全局生效的。官方原文：

修改供应商配置后，所有引用该供应商的模型都会同步生效，无需逐个模型修改。

好处是换代理、迁域名只改一处；风险也在这——一次误改会影响所有挂在这个供应商下的模型。建议动 API Base 前先确认这个供应商下面挂了几个模型。

第二，删除模型前必须查引用。官方警告：删除模型前请确认该模型未被智能体或工作流节点引用，否则相关功能将失效。删模型是二次确认操作，删除后无法恢复。

第三，两处「记忆轮数」上限不一样。

工作流节点的上限明显更小。如果你的长周期场景依赖工作流节点携带历史，先记住 10 轮这个天花板，不够用就得在流程里显式读写长期记忆库。

第四，节点上下文记忆不一定是你想要的。官方对工作流节点记忆有一条提示：

工作流运行的输入输出记录，是经过了本工作流内部所有节点加工后得出（不包含运行过程），可能与模型要解决问题无关。请根据实际需求，决定是否开启。

第五，页面没标版本的能力，不要自己推断。本文涉及的模型模块、模型介绍、数据库、知识库四个页面，官方均未标注版本要求。这不等于「任何版本都能用」——只能说这几页没有给出结论。自部署接入这类偏生产环境的能力，实际是否开通以你所用平台的版本为准。

十、上线前检查清单

按顺序做，每一条都能省掉一类返工。

1. 确认推理服务暴露的是 OpenAI 兼容接口（/v1/chat/completions规范），不是自有协议；
2. 记录服务端暴露的模型标识（vLLM 看--served-model-name，Ollama 看名称:标签，Xinference 看启动返回的名称）；
3. 本机curl测通，确认model字段填对能返回内容；
4. 从平台侧网络curl测通，排除防火墙 / 安全组问题；
5. 压一个长输入请求，确认链路稳定、不超时；
6. API Base 填到/v1/这一层，不要只填到端口；
7. API-Key 用子账号 Key，按最小权限配置；编辑时留空表示保持不变；
8. 模型名称与供应商接口标识严格一致，别填成给自己看的备注；
9. 最大上下文按模型原生容量填，不要往大写；
10. 确认这个供应商下面挂了几个模型，再决定要不要动 API Base；
11. 建好「code → 模型」的映射表，用于日志归因（响应里的model字段回填的是 code）；
12. 算一遍上下文：记忆轮次 + 智能体设定 + 知识库命中量 + 问题 + 回复，别超过智能体的最大上下文长度；
13. 知识库场景把温度收到0.3以内；
14. 明确 Embedding 不可自选，如果场景对此有硬要求，提前确认；
15. 确认要换多模态模型时走插件路径，而不是在模型模块里找。

写在最后

模型的接入难度，其实不在「怎么填」，而在**「填在哪一层」**。

把三句话记住，这套平台的模型层基本就不会走弯路：

1. 协议只有一条：OpenAI 兼容，vLLM / Ollama / Xinference 都是围着它做暴露；
2. 配置分四层：模型资产池、智能体、工作流节点、数据库 SQL 模型，各管各的作用域；
3. 参数只在平台侧生效：API 里传什么都会被忽略，换模型、改温度都得回平台。

最后一句：本文参数与字段均按官方文档整理，请以你所用平台的最新文档为准——模型清单类信息变动较快，接入前建议再核对一次。

相关文章

• 开放 API：把平台接进你自己的系统（端点、鉴权、SSE 流式与thread_id）
• AI Agent 为什么总「失忆」？长期记忆库的设计与使用
• 企业知识库搭建全流程：从文档导入到检索策略调优

你的自部署模型是怎么接进来的？踩过模型名称不一致的坑吗？评论区聊聊，我看到会回。