自部署模型怎么接进来三个框架接入实录面向私有化部署与模型运维讲清一套零代码 AI 智能体平台的模型层怎么配、自部署模型怎么接、以及哪些参数你以为能改其实改不了。先说结论接自部署模型只有一条硬要求——服务端必须暴露 OpenAI 兼容接口/v1/chat/completions那一套规范。满足它vLLM、Ollama、Xinference 都能接不满足改再多配置也没用。同时有三件事我先说在前面因为它们比接入步骤更容易让人白折腾半天平台里的「模型」配置分散在多个模块作用范围完全不同改错地方等于没改通过 API 调用时请求体里的model和temperature会被服务端忽略参数以平台侧配置为准供应商配置是全局的——改一次 API Base所有引用它的模型一起生效。下面按「先看全貌 → 再看协议 → 接入实录 → 边界与坑」的顺序展开。一、先看全貌模型配置分散在多个模块很多人第一次找「换模型」的入口会在控制台里转好几圈原因是这套平台的模型配置按作用域分散在不同模块不是集中在一个「模型设置」页里。配置位置作用范围能否用自定义模型关键配置项模型模块 → 模型管理全局资产池供上层选用可以新建供应商、API Base、API-Key、模型名称、最大上下文、默认上下文智能体 → 模型配置该智能体的网页端对话 全部接入渠道可以选择默认模型、对话可选模型、温度、记忆轮次、最大上下文长度工作流 → 大模型节点仅该节点可以选择节点级模型、节点级温度、系统提示词、上下文记忆最多 10 轮数据库 → 数据库模型仅「生成 SQL」这一次调用可以选择单独指定用于生成 SQL 的模型知识库 → 向量化模型知识库检索不能选系统内置无表里前四行是可以选定模型的位置最后一行不提供选择——这点在第二节单独展开。这张表是本文最该先记住的东西。后面的坑基本都源于把某一层的作用范围记错了。举两个常见误判在工作流大模型节点里把温度调成 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 官方给出的三条兼容路径路径说明OpenAI 官方接口原生兼容国内厂商兼容接口深度求索、通义千问、智谱 AI、Kimi 等均提供 OpenAI 兼容模式私有化部署通过 vLLM、Ollama、Xinference 等推理框架暴露 OpenAI 兼容接口一个值得注意的细节Kimi 出现在这里但不在内置大语言模型清单里内置清单是智谱 AI、豆包、深度求索、七牛云、通义千问、CloseAI 六家。也就是说如果你要用 Kimi走的是自定义模型的兼容接口这条路而不是从内置列表里选。这类「清单和路径不完全对应」的地方建议以文档原文分页为准去核对别按印象推断。3.3 新增供应商五个字段配置项必填说明供应商名称是服务商显示名称API Base是OpenAI 兼容的服务地址例如https://api.example.com/v1/API Key是接口访问凭证密码模式录入保存后不可见描述否供应商说明最长30字符供应商标识否logo 图片支持BMP/JPEG/JPG/GIF/PNG不超过2M官方关于 API Key 的三条安全提醒值得照做API Key 是访问模型服务的核心凭证请妥善保管提交后系统不再明文回显编辑时留空表示保持原 Key 不变建议使用供应商提供的子账号 Key按需配置最小权限。第二条在运维上很关键因为不回显所以「忘了填就保存」不会把 Key 清空——这点比很多人预期的安全。3.4 创建模型六个字段点「自定义模型」按钮先选供应商再填模型信息配置项必填说明模型供应商是下拉选择如未创建可点「新增供应商」即时添加模型名称是模型显示名称同时作为调用接口时的model参数模型分类是多选模型能力类型描述否最长30字符最大上下文是模型支持的最大 Token 上限≥1默认上下文是默认使用的上下文长度≥1不得超过最大上下文选择供应商后系统会自动填充该供应商的 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 三个框架的定位差异框架更适合的场景模型标识的确定方式默认端口vLLMGPU 服务器上跑生产追求吞吐与并发启动时用--served-model-name指定8000Ollama单机快速验证、小规模部署名称:标签11434Xinference多模型统一管理、需要多副本启动时返回的模型 UID / 名称9997选哪个不影响接入方式——只要它暴露的是 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/v1Ollama# 拉起服务并准备模型ollama serve ollama pull qwen2.5:7b# 暴露出来的 OpenAI 兼容端点# http://{内网IP}:11434/v1# 模型标识qwen2.5:7bXinference# 启动服务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\-HContent-Type: application/json\-d{ model: qwen2.5-7b, messages: [{role: user, content: 你好}] }第二步从平台侧能访问的网络里测通把127.0.0.1换成服务器内网 IP在与被调用的业务系统同网段的机器上再跑一次。这一步失败通常是防火墙、安全组或容器网络没放行而不是平台的问题。第三步压一个长请求确认链路稳定官方要求里还有两个字是「稳定」。用一条长输入比如带几百字上下文的请求跑几次看是否出现超时或截断。短请求能通、长请求被网关掐断在自部署环境里并不少见。4.4 填进平台三步都通了再回到模型模块配置字段自部署场景怎么填供应商名称自取建议带上环境如「内网推理集群」API Basehttp://{内网IP}:8000/v1/填到/v1/内网地址API-Key见下方说明模型名称必须等于服务端暴露的模型标识如qwen2.5-7b最大上下文按模型实际原生容量填别为了「看起来能装」往大写默认上下文≤ 最大上下文关于 API Key 有一个实践惯例要讲清楚多数自部署推理框架默认不校验 API Key但平台这个字段是必填的所以通常填一个占位字符串即可如果你的推理服务前面挂了网关如 OpenAI 兼容代理、各类 AI 网关网关可能会真的校验 Key这时就要填实际的值。这条以你的部署为准——不要因为「vLLM 不校验」就假设整条链路不校验。五、上下文一条四层约束链上下文长度是接入模型时最容易算错的东西因为平台里有四层都在管它。任何一层算小了表现都是「知识被截断、回答变差」而且报错信息不会直接告诉你是哪一层。层级参数来源模型级最大上下文 / 默认上下文默认 ≤ 最大模型信息智能体级最大上下文长度不得超过模型原生支持的容量智能体模型配置知识库级单条语料长度 × 检索返回条数知识库检索策略API 级无状态对话的上下文长度受所选模型最大上下文限制开放 API智能体这一层官方给了一个明确的构成公式上下文长度 保存的记忆轮次的问 答内容 智能体设定 本次提问知识库命中内容 本次用户问题 本次模型回复知识库这一层官方的提醒是可依据单条长度、检索返回条数预估单次对话带入知识库内容总字符量该总量不可超过模型配置的最大上下文长度否则会截断知识内容、影响回答效果。一个口径提示公式里的「轮次问答」「用户问题」用的都是 Token而知识库那一段官方用的是字符。这两者不是 1:1 的关系。所以做容量估算时知识库部分要先按实际分词结果折算再代入 Token 口径的公式——直接拿字符数当 Token 数相加是最常见的估算错误。实践结论算上下文要从最窄的一层倒推。模型的最大上下文是天花板但真正决定效果的是「记忆轮次 知识库命中量」这两项之和——它们才是你实际能控制、也最容易被调过头的部分。六、温度与模型参数在哪儿配才生效6.1 先说最反直觉的一条OpenAPI 的兼容性说明里写得很清楚请求体接受model、temperature等 OpenAI SDK 附带字段但会被忽略——智能体使用自身配置的模型与参数。官方的 SDK 示例里也带着注释fromopenaiimportOpenAI clientOpenAI(api_key{api_key},base_urlhttps://{host}/ai/open/v1/agent,# SDK 会自动拼接 /chat/completions)streamclient.chat.completions.create(modelagent_xxx,# SDK 必填字段,服务端忽略,可填 code 值messages[{role:user,content:你好}],extra_body{code:agent_xxx},# code 等自定义字段经 extra_body 传入streamTrue,)第一行注释就是答案model是 SDK 的必填字段所以你必须传但服务端不看它可以随便填成 code 值。这条的工程后果参数只在平台侧生效客户端改不动。6.2 温度的两个生效点生效点影响范围说明智能体 → 模型配置 → 温度网页端对话、全部接入渠道、开放 API 调用调节生成随机性取值越大创意度越高、越小表述越严谨工作流 → 大模型节点 → 温度仅该节点温度越高回复创意性越强、不确定性越高越低越严谨、稳定同一个模块里还有一项容易和温度混着调的配置——记忆轮次0~50轮管的是对话上下文保留多少轮跟生成风格无关。两者建议分开调一起动的话效果差异分不清是哪一项带来的。官方还给了场景化的建议知识库问答业务场景温度建议上限0.3。这条建议的适用范围值得展开一下——知识库问答要的是「照着语料答」温度拉高会让模型开始自由发挥命中率反而下降。而如果你的智能体更像是创意助手那这个 0.3 就不适用。6.3 一个架构层面的结论把上面两条连起来看会得到一个会影响接口设计的结论「同一个智能体给 A 客户 0.1 的温度、给 B 客户 0.8 的温度」——在 API 层做不到。因为temperature传进去会被忽略。要实现这种差异只有两条路在平台上建两个智能体各自配好温度调用方按code区分把「按参数分叉」的逻辑做进工作流——不同分支走到不同的大模型节点利用节点级温度实现。同样地这也解释了为什么 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 × 输出单价。这里有两点必须说清否则做成本预估时一定会算错第一「仅内置模型」这四个字很重要。自定义模型的费用发生在你自己的供应商侧自部署的算力成本、或云端厂商的账单平台侧不展示它的单价。所以自部署接入的模型在平台账单里不会出现模型费这一项——这也是私有化场景下「模型成本可控」的原因。第二Token 单价是这里的分档展示口径而平台账户侧的实际消耗单位是「粒子」。这个区分在知识库页能看得很直观上传文档时页面左下方会展示当前文件总 Token 数并同步生成预估粒子知识库的智能解析按15 粒子 / 页计费。实践结论与业务侧对账时用账户侧的「粒子」口径做用量日志分析时用usage里的 Token 字段——这是两个不同层面的口径不要混成一句话说。九、五个最容易踩的兼容性边界把全文的边界集中在这里都是「你以为会生效、实际不会」的类型。第一供应商配置是全局生效的。官方原文修改供应商配置后所有引用该供应商的模型都会同步生效无需逐个模型修改。好处是换代理、迁域名只改一处风险也在这——一次误改会影响所有挂在这个供应商下的模型。建议动 API Base 前先确认这个供应商下面挂了几个模型。第二删除模型前必须查引用。官方警告删除模型前请确认该模型未被智能体或工作流节点引用否则相关功能将失效。删模型是二次确认操作删除后无法恢复。第三两处「记忆轮数」上限不一样。位置上限智能体 → 模型配置 → 记忆轮次0~50轮工作流 → 大模型节点 → 上下文记忆最大10轮工作流节点的上限明显更小。如果你的长周期场景依赖工作流节点携带历史先记住 10 轮这个天花板不够用就得在流程里显式读写长期记忆库。第四节点上下文记忆不一定是你想要的。官方对工作流节点记忆有一条提示工作流运行的输入输出记录是经过了本工作流内部所有节点加工后得出不包含运行过程可能与模型要解决问题无关。请根据实际需求决定是否开启。第五页面没标版本的能力不要自己推断。本文涉及的模型模块、模型介绍、数据库、知识库四个页面官方均未标注版本要求。这不等于「任何版本都能用」——只能说这几页没有给出结论。自部署接入这类偏生产环境的能力实际是否开通以你所用平台的版本为准。十、上线前检查清单按顺序做每一条都能省掉一类返工。确认推理服务暴露的是 OpenAI 兼容接口/v1/chat/completions规范不是自有协议记录服务端暴露的模型标识vLLM 看--served-model-nameOllama 看名称:标签Xinference 看启动返回的名称本机curl测通确认model字段填对能返回内容从平台侧网络curl测通排除防火墙 / 安全组问题压一个长输入请求确认链路稳定、不超时API Base 填到/v1/这一层不要只填到端口API-Key 用子账号 Key按最小权限配置编辑时留空表示保持不变模型名称与供应商接口标识严格一致别填成给自己看的备注最大上下文按模型原生容量填不要往大写确认这个供应商下面挂了几个模型再决定要不要动 API Base建好「code → 模型」的映射表用于日志归因响应里的model字段回填的是 code算一遍上下文记忆轮次 智能体设定 知识库命中量 问题 回复别超过智能体的最大上下文长度知识库场景把温度收到0.3以内明确 Embedding 不可自选如果场景对此有硬要求提前确认确认要换多模态模型时走插件路径而不是在模型模块里找。写在最后模型的接入难度其实不在「怎么填」而在**「填在哪一层」**。把三句话记住这套平台的模型层基本就不会走弯路协议只有一条OpenAI 兼容vLLM / Ollama / Xinference 都是围着它做暴露配置分四层模型资产池、智能体、工作流节点、数据库 SQL 模型各管各的作用域参数只在平台侧生效API 里传什么都会被忽略换模型、改温度都得回平台。最后一句本文参数与字段均按官方文档整理请以你所用平台的最新文档为准——模型清单类信息变动较快接入前建议再核对一次。相关文章开放 API把平台接进你自己的系统端点、鉴权、SSE 流式与thread_idAI Agent 为什么总「失忆」长期记忆库的设计与使用企业知识库搭建全流程从文档导入到检索策略调优你的自部署模型是怎么接进来的踩过模型名称不一致的坑吗评论区聊聊我看到会回。