摘要
摘要 :常见的错误写法是照搬一段 YAML:
provider.type: openai、apiKey、baseURL,还列了timeout、retry、streaming、cost_observable四个"参数"。对照官方文档会发现,Nexent 模型配置是界面表单,单个模型只有模型名称、展示名称、模型 URL、API Key 四项,另有 8 类模型类型下拉和 9 个系统模型槽位;所谓超时、重试、流式、成本开关都不在这个页面。本文按官方流程写清"添加单个模型 → 批量添加 → 配置系统槽位 → 检查连通性"的完整操作,给出 7 家服务商的 API Key 获取入口与真实 URL 示例,并把流式输出、超时与重试、用量与成本观察这三项常见诉求落到平台里真实存在的位置。
文章目录
-
- 摘要
- 一、为什么模型页找不到这些字段:背景与常见误写
- 二、环境与版本:模型类型与核心槽位介绍
- 三、操作步骤:官方模型配置页的四段流程
-
- [3.1 添加单个模型(4 个字段 + 1 次连通性验证)](#3.1 添加单个模型(4 个字段 + 1 次连通性验证))
- [3.2 批量添加模型(注意:拉回来的默认是关的)](#3.2 批量添加模型(注意:拉回来的默认是关的))
- [3.3 配置系统模型槽位(9 个下拉框)](#3.3 配置系统模型槽位(9 个下拉框))
- [3.4 检查模型连通性](#3.4 检查模型连通性)
- [四、不同厂商的 API Key 获取路径与接入方式](#四、不同厂商的 API Key 获取路径与接入方式)
-
- [4.1 大语言模型(官方页面列出的服务商)](#4.1 大语言模型(官方页面列出的服务商))
- [4.2 三类模型的 URL 差异(最容易填错)](#4.2 三类模型的 URL 差异(最容易填错))
- [4.3 三项常见诉求的真实落点](#4.3 三项常见诉求的真实落点)
- [4.4 代理与网络:容器内访问宿主机模型](#4.4 代理与网络:容器内访问宿主机模型)
- [4.5 配置安全](#4.5 配置安全)
- 五、结果验证与真实截图采集
- 六、常见问题
- 七、总结
- 参考资料
一、为什么模型页找不到这些字段:背景与常见误写
| 源笔记字段 | 官方模型配置页是否存在 | 真实对应 |
|---|---|---|
provider.type: openai |
无 | "模型类型下拉框"的 8 个中文选项 |
apiKey / baseURL |
无此英文表单名 | API Key、模型URL(必填) |
timeout / retry |
无 | 平台无模型级超时/重试开关;沙箱有 NEXENT_SANDBOX_TIMEOUT_S |
streaming |
无 | 运行时用 SSE 流式返回结果,属架构行为,不是模型开关 |
cost_observable |
无 | 用量与配额在厂商控制台;平台侧可开 monitoring 观测组件 |
很多配置笔记会顺手写上"流式输出、超时与重试、用量与成本观察",但需求存在不等于界面上有对应开关。把这些词当成"在 Nexent 配置页勾选"的字段,只会让读者在界面里找不到。正确写法是:先讲清楚模型页真正有什么,再说明这三项诉求在平台的哪个位置满足。

图1:虚构配置字段与官方四项表单字段的对照图。
二、环境与版本:模型类型与核心槽位介绍
| 项目 | 采集方式 | 你的实测值 |
|---|---|---|
| Nexent 版本 | 仓库根 cat VERSION / 页面左下角 |
【待实测填写】 |
| 登录账号角色 | 必须是租户管理员,超管无业务菜单 | 【待实测填写】 |
| 使用的大语言模型 | 如 Qwen/Qwen3-8B |
【待实测填写】 |
| 使用的向量模型 | 如 BAAI/bge-m3 |
【待实测填写】 |
| 服务商 | 硅基流动 / 阿里云百炼 / 其他 | 【待实测填写】 |
| API Key 获取时间 | 厂商控制台创建时间 | 【待实测填写】 |
前置条件:平台已按 bash deploy.sh docker 部署完成、超管已创建租户与租户管理员、当前用租户管理员登录。模型配置页路径:用户指南 → 智能体开发 → 模型配置,平台内对应左侧"模型管理"。
官方给出的接入前提原文:"Nexent 支持任何遵循 OpenAI API 规范的大语言模型供应商"。
三、操作步骤:官方模型配置页的四段流程
3.1 添加单个模型(4 个字段 + 1 次连通性验证)
- 点击 "添加模型" 按钮,进入添加模型弹窗;
- 点击模型类型下拉框 ,从 8 个选项中选一个:
大语言模型 / 向量模型 / 图片理解模型 / 图片生成模型 / 视频理解模型 / 重排模型 / 语音识别模型 / 语音合成模型; - 填写表单:
| 字段 | 是否必填 | 官方说明 | 示例值 |
|---|---|---|---|
| 模型名称 | 必填 | 请求体中的模型名称,格式通常是 模型系列/模型名字 |
Qwen/Qwen3-8B、BAAI/bge-m3 |
| 展示名称 | 否 | 默认与模型名称相同 | 可留空 |
| 模型URL | 必填 | 服务商 API 端点,一般以 /v1 结尾 |
https://api.siliconflow.cn/v1 |
| API Key | 单条未标必填,批量标必填 | 服务商密钥管理页创建 | 【待实测填写】 |
- 点击 "连通性验证",系统发送测试请求并返回结果;
- 点击 "确定",模型进入可用模型列表。
官方给出的三条注意事项,照抄一遍避免踩坑:
- 模型名称通常格式为
模型系列/模型名字,例如Qwen+Qwen3-8B→Qwen/Qwen3-8B; - 模型 URL 从服务商 API 文档获取:硅基流动的大语言模型是
https://api.siliconflow.cn/v1,向量模型是https://api.siliconflow.cn/v1/embeddings,视觉语言模型仍是https://api.siliconflow.cn/v1; - API Key 在服务商的"API Key 密钥管理"页创建并获取。
3.2 批量添加模型(注意:拉回来的默认是关的)
- 在添加模型弹窗中打开 "批量添加模型开关";
- 点击模型提供商下拉框选择服务商;
- 选择模型类型(同样是那 8 类);
- 输入 API Key(必填);
- 点 "获取模型" 批量拉取模型列表;
- 手动点开关启用所需模型------官方原文:"获取到的模型默认是未启用的";
- 点 "确定" 保存。
这一步是新手最常卡住的地方:拉回来一堆模型却一个都选不了,因为没点启用开关。
3.3 配置系统模型槽位(9 个下拉框)
添加模型后还要把模型指派给系统槽位,否则平台核心功能没有模型可用。
| 槽位 | 作用(官方说明摘录) |
|---|---|
| 基础模型 | 标题生成、实时文件读取、基础文本处理 |
| 大语言模型 | 核心推理引擎,处理自然语言请求、生成回复、执行代码、分析数据 |
| 向量模型 | 知识库文本与图片向量化,影响检索准确率与知识库稳定性 |
| 重排模型 | 初筛后语义匹配与评分,让最相关答案排首位 |
| 图片理解模型 | 分析理解图片内容;对话页上传图片时自动调用多模态模型 |
| 图片生成模型 | 文本描述生成图像 |
| 视频理解模型 | 视频内容分析、摘要、问答 |
| 语音合成模型 | 文本转语音(TTS) |
| 语音识别模型 | 语音转文本(STT) |
操作:逐个点击对应下拉框,从已添加的同类模型中选择。官方特别提醒:向量模型配置会影响知识库稳定运行,"根据模型能力选择合适的文档切片大小和单次请求切片量。切片越小,系统越稳定,但文件解析质量也会受到影响"。
语音模型目前支持阿里灵积 和火山引擎 :阿里灵积配置与大语言模型相同的 apikey;火山引擎需要 appid 与 token,在"添加模型"页面配置 TTS/STT 设置。
3.4 检查模型连通性
点击 "检查模型连通性" ,系统自动测试所有已配置的系统模型(不是所有已添加模型)。状态含义:
| 指示 | 含义 | 处理 |
|---|---|---|
| 🔵 蓝色圆点 | 正在检测中 | 等待 |
| 🔴 红色圆点 | 连接失败 | 检查配置或网络状态 |
| 🟢 绿色圆点 | 连接正常 | 可正常使用 |
官方给的失败排查四项:网络连接是否稳定、API 密钥是否有效且未过期、模型服务商服务状态、防火墙与安全策略。
#mermaid-svg-DN8ct9Dj6cPITGCH{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-DN8ct9Dj6cPITGCH .error-icon{fill:#552222;}#mermaid-svg-DN8ct9Dj6cPITGCH .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-DN8ct9Dj6cPITGCH .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-DN8ct9Dj6cPITGCH .marker{fill:#333333;stroke:#333333;}#mermaid-svg-DN8ct9Dj6cPITGCH .marker.cross{stroke:#333333;}#mermaid-svg-DN8ct9Dj6cPITGCH svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-DN8ct9Dj6cPITGCH p{margin:0;}#mermaid-svg-DN8ct9Dj6cPITGCH .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster-label text{fill:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster-label span{color:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster-label span p{background-color:transparent;}#mermaid-svg-DN8ct9Dj6cPITGCH .label text,#mermaid-svg-DN8ct9Dj6cPITGCH span{fill:#333;color:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH .node rect,#mermaid-svg-DN8ct9Dj6cPITGCH .node circle,#mermaid-svg-DN8ct9Dj6cPITGCH .node ellipse,#mermaid-svg-DN8ct9Dj6cPITGCH .node polygon,#mermaid-svg-DN8ct9Dj6cPITGCH .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-DN8ct9Dj6cPITGCH .rough-node .label text,#mermaid-svg-DN8ct9Dj6cPITGCH .node .label text,#mermaid-svg-DN8ct9Dj6cPITGCH .image-shape .label,#mermaid-svg-DN8ct9Dj6cPITGCH .icon-shape .label{text-anchor:middle;}#mermaid-svg-DN8ct9Dj6cPITGCH .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-DN8ct9Dj6cPITGCH .rough-node .label,#mermaid-svg-DN8ct9Dj6cPITGCH .node .label,#mermaid-svg-DN8ct9Dj6cPITGCH .image-shape .label,#mermaid-svg-DN8ct9Dj6cPITGCH .icon-shape .label{text-align:center;}#mermaid-svg-DN8ct9Dj6cPITGCH .node.clickable{cursor:pointer;}#mermaid-svg-DN8ct9Dj6cPITGCH .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-DN8ct9Dj6cPITGCH .arrowheadPath{fill:#333333;}#mermaid-svg-DN8ct9Dj6cPITGCH .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-DN8ct9Dj6cPITGCH .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-DN8ct9Dj6cPITGCH .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DN8ct9Dj6cPITGCH .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-DN8ct9Dj6cPITGCH .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DN8ct9Dj6cPITGCH .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster text{fill:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH .cluster span{color:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-DN8ct9Dj6cPITGCH .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-DN8ct9Dj6cPITGCH rect.text{fill:none;stroke-width:0;}#mermaid-svg-DN8ct9Dj6cPITGCH .icon-shape,#mermaid-svg-DN8ct9Dj6cPITGCH .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-DN8ct9Dj6cPITGCH .icon-shape p,#mermaid-svg-DN8ct9Dj6cPITGCH .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-DN8ct9Dj6cPITGCH .icon-shape .label rect,#mermaid-svg-DN8ct9Dj6cPITGCH .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-DN8ct9Dj6cPITGCH .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-DN8ct9Dj6cPITGCH .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-DN8ct9Dj6cPITGCH :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 否
是
否
是
租户管理员登录
添加模型 / 选择 8 类中一类
填模型名称 展示名称 模型URL API Key
连通性验证
验证通过
确定 保存至可用模型列表
配置 9 个系统模型槽位
检查模型连通性
全绿
进入知识库与智能体配置
从"点击验证"到"三色圆点"的调用关系,用时序图看得更清楚:
系统模型槽位 服务商接口 模型配置页 租户管理员 系统模型槽位 服务商接口 模型配置页 租户管理员 #mermaid-svg-LTZdZNk1MRWcXndg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-LTZdZNk1MRWcXndg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-LTZdZNk1MRWcXndg .error-icon{fill:#552222;}#mermaid-svg-LTZdZNk1MRWcXndg .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-LTZdZNk1MRWcXndg .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-LTZdZNk1MRWcXndg .marker{fill:#333333;stroke:#333333;}#mermaid-svg-LTZdZNk1MRWcXndg .marker.cross{stroke:#333333;}#mermaid-svg-LTZdZNk1MRWcXndg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-LTZdZNk1MRWcXndg p{margin:0;}#mermaid-svg-LTZdZNk1MRWcXndg .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LTZdZNk1MRWcXndg text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-LTZdZNk1MRWcXndg .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-LTZdZNk1MRWcXndg .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-LTZdZNk1MRWcXndg .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-LTZdZNk1MRWcXndg .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-LTZdZNk1MRWcXndg #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-LTZdZNk1MRWcXndg .sequenceNumber{fill:white;}#mermaid-svg-LTZdZNk1MRWcXndg #sequencenumber{fill:#333;}#mermaid-svg-LTZdZNk1MRWcXndg #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-LTZdZNk1MRWcXndg .messageText{fill:#333;stroke:none;}#mermaid-svg-LTZdZNk1MRWcXndg .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LTZdZNk1MRWcXndg .labelText,#mermaid-svg-LTZdZNk1MRWcXndg .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-LTZdZNk1MRWcXndg .loopText,#mermaid-svg-LTZdZNk1MRWcXndg .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-LTZdZNk1MRWcXndg .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-LTZdZNk1MRWcXndg .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-LTZdZNk1MRWcXndg .noteText,#mermaid-svg-LTZdZNk1MRWcXndg .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-LTZdZNk1MRWcXndg .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LTZdZNk1MRWcXndg .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LTZdZNk1MRWcXndg .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-LTZdZNk1MRWcXndg .actorPopupMenu{position:absolute;}#mermaid-svg-LTZdZNk1MRWcXndg .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-LTZdZNk1MRWcXndg .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-LTZdZNk1MRWcXndg .actor-man circle,#mermaid-svg-LTZdZNk1MRWcXndg line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-LTZdZNk1MRWcXndg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 添加模型 填写 4 个字段 点击 连通性验证 发送测试请求 返回验证结果 显示通过或失败 指派模型到系统槽位 点击 检查模型连通性 批量测试已配置的系统模型 返回各模型状态 显示 蓝/红/绿 三色圆点

图2:四项字段八类类型九个槽位的模型配置全景。
四、不同厂商的 API Key 获取路径与接入方式
4.1 大语言模型(官方页面列出的服务商)
| 服务商 | 官方入口 | 接入四步 |
|---|---|---|
| 硅基流动 | https://siliconflow.cn/ | 注册 → 创建并复制 API Key → 查 API 端点(/v1 结尾)→ 在 Nexent 点"添加自定义模型"填信息 |
| 阿里云百炼 | https://bailian.console.aliyun.com/ | 同上 |
| 小马算力 | https://www.tokenpony.cn/ | 同上 |
| Deepseek | https://platform.deepseek.com/ | 同上 |
| OpenAI | https://platform.openai.com/ | 同上 |
| Anthropic | https://console.anthropic.com/ | 同上 |
| 月之暗面 | https://platform.moonshot.cn/ | 同上 |
上面"接入四步"是官方原文给出的通用流程。各厂商控制台的具体菜单名、免费额度、Key 前缀请以你当次操作为准,逐项截屏并填入【待实测填写】,不要凭印象填。
4.2 三类模型的 URL 差异(最容易填错)
text
大语言模型 URL : https://api.siliconflow.cn/v1
视觉语言模型URL: https://api.siliconflow.cn/v1
向量模型 URL : https://api.siliconflow.cn/v1/embeddings
重排模型 URL : 一般以 /v1/rerank 结尾
模型名称 : Qwen/Qwen3-8B
多模态模型名 : Qwen/Qwen2.5-VL-32B-Instruct
向量模型名 : BAAI/bge-m3
注意:多模态模型使用与大语言模型相同的 API Key 和模型 URL,只是换模型名称 ;向量、重排则是同一把 Key、不同 URL 路径。把 /v1 直接填给向量模型,是"连通性验证"红灯的高频原因。
4.3 三项常见诉求的真实落点
| 常见诉求 | 平台真实位置 | 可操作做法 |
|---|---|---|
| 流式输出 | 无模型页开关 | 架构层用 SSE 持续返回智能体执行结果;在"开始问答"里观察逐字输出即可验证,无需配置 |
| 超时与重试 | 无模型级开关 | 沙箱级有 NEXENT_SANDBOX_TIMEOUT_S(默认 30,单步执行超时,单位秒),在 deploy/env/.env 配置;改资源/网络/Shell 策略后需重新部署 Runtime |
| 用量与成本观察 | 无模型页开关 | ① 厂商控制台查配额与账单(官方"需要帮助"明确写"验证 API 密钥权限和配额");② 部署时勾选 monitoring 组件启用 OpenTelemetry |
监控组件的真实启用方式与地址:
bash
# 交互式部署时勾选 monitoring 组件;若已有 deploy.options,选择重新配置/覆盖
cd nexent
bash deploy.sh docker
# 需要自定义监控变量时
cp deploy/env/monitoring.env.example deploy/env/monitoring.env
monitoring 是部署脚本 TUI 里的可选组件,勾上后才有平台内的调用观测数据;已经部署过的环境若 deploy.options 存在,脚本默认复用旧选项,必须在 TUI 里明确选择重新配置,否则新勾的组件不会写进配置。这条注释提醒的是"改配置要重跑一次部署",而不是"改个环境变量就生效"。预期现象是重新部署后 docker ps 里出现监控相关容器;若不需要用量观测,直接看服务商控制台的账单页也可以,两条路径取其一即可。
| Provider | 默认访问地址 |
|---|---|
otlp |
仅 Collector,无 Dashboard |
phoenix |
http://localhost:6006 |
langfuse |
http://localhost:3001 |
langsmith |
https://smith.langchain.com/ |
grafana |
http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1 |
zipkin |
http://localhost:9411 |
4.4 代理与网络:容器内访问宿主机模型
官方 FAQ 明确容器里的 localhost 指向容器自身。若用本机 Ollama 之类服务:
text
# macOS / Windows,或已配置该 DNS 的 Linux Docker
http://host.docker.internal:11434/v1
# 或宿主机真实 IP(需防火墙放行)
http://[宿主机IP]:11434/v1
这段说明对应的是 host.docker.internal 在不同宿主上的可达性:桌面版 Docker 自带该域名解析,Linux 则需要在 compose 里显式加 extra_hosts 才能指向宿主机。判断方法很简单------在容器内执行 getent hosts host.docker.internal,能返回 IP 才能把它写进本地模型服务地址;返回空就别用这个域名,改用宿主机在 Docker 网桥上的实际地址,并在【待实测填写】里记下你采用的写法。
yaml
extra_hosts:
- "host.docker.internal:host-gateway"
此外,模型"消息格式不兼容"也是官方 FAQ 的真实高频问题:有些纯文本接口只接受字符串 content,不接受内容块数组。
python
# 多模态接口可能使用
{ "role": "user", "content": [ { "type": "text", "text": "prompt" } ] }
# 纯文本接口可能只接受
{ "role": "user", "content": "prompt" }
遇到此类报错,改用兼容 OpenAI 多模态消息的接口,或把该模型配置为对应的纯文本模型类型。
4.5 配置安全
bash
# deploy/env/.env 中可覆盖的默认凭据,生产必须改
NEXENT_SUPER_ADMIN_PASSWORD=<你的强密码>
LANGFUSE_INIT_USER_PASSWORD=<替换默认值>
GRAFANA_ADMIN_PASSWORD=<替换默认值>
ENCRYPTION_KEY=<替换默认值>
官方生产建议:替换默认密码、密钥与 Langfuse ENCRYPTION_KEY,并通过反向代理或防火墙限制 Dashboard、Collector 端口访问范围。API Key 不要写进文章、截图或 Git 提交。
图:模型连通性三色圆点的状态迁移
流程图讲配置顺序、时序图讲调用顺序,这张状态图只讲一个模型条目从录入到可用的状态变化。蓝点表示尚未检测,红点要回到 URL 与 Key 排查,绿点才意味着可以绑定到系统槽位。
#mermaid-svg-4QMG9QBnlxUvW8ED{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-4QMG9QBnlxUvW8ED .error-icon{fill:#552222;}#mermaid-svg-4QMG9QBnlxUvW8ED .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-4QMG9QBnlxUvW8ED .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-4QMG9QBnlxUvW8ED .marker{fill:#333333;stroke:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED .marker.cross{stroke:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-4QMG9QBnlxUvW8ED p{margin:0;}#mermaid-svg-4QMG9QBnlxUvW8ED defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-4QMG9QBnlxUvW8ED g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-4QMG9QBnlxUvW8ED g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-4QMG9QBnlxUvW8ED g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-4QMG9QBnlxUvW8ED g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-4QMG9QBnlxUvW8ED .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-4QMG9QBnlxUvW8ED .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-4QMG9QBnlxUvW8ED .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-4QMG9QBnlxUvW8ED .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-4QMG9QBnlxUvW8ED .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-4QMG9QBnlxUvW8ED .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-4QMG9QBnlxUvW8ED .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-4QMG9QBnlxUvW8ED .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-4QMG9QBnlxUvW8ED .edgeLabel .label text{fill:#333;}#mermaid-svg-4QMG9QBnlxUvW8ED .label div .edgeLabel{color:#333;}#mermaid-svg-4QMG9QBnlxUvW8ED .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-4QMG9QBnlxUvW8ED .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-4QMG9QBnlxUvW8ED .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-4QMG9QBnlxUvW8ED .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED #statediagram-barbEnd{fill:#333333;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-4QMG9QBnlxUvW8ED .cluster-label,#mermaid-svg-4QMG9QBnlxUvW8ED .nodeLabel{color:#131300;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-4QMG9QBnlxUvW8ED .note-edge{stroke-dasharray:5;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-note text{fill:black;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram-note .nodeLabel{color:black;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagram .edgeLabel{color:red;}#mermaid-svg-4QMG9QBnlxUvW8ED #dependencyStart,#mermaid-svg-4QMG9QBnlxUvW8ED #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-4QMG9QBnlxUvW8ED .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-4QMG9QBnlxUvW8ED :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 点击检查模型连通性
鉴权与接口均通过
地址或密钥异常
修正 URL 后缀或 API Key
指派到系统模型槽位
工作台调用成功
未检测
检测中
可用(绿点)
失败(红点)
已绑定

图3:系统槽位用途与连通性验证结果的矩阵t图。
五、结果验证与真实截图采集
三项通过标准:
| 验证项 | 判断依据 |
|---|---|
| 单模型连通 | "连通性验证"返回成功,模型出现在可用模型列表 |
| 系统槽位齐备 | 9 个槽位中至少基础模型、大语言模型、向量模型已选定 |
| 整体连通 | "检查模型连通性"全部显示 🟢 绿色圆点 |
六、常见问题
Q1:模型无法连接? 官方 FAQ 四项:正确的 base URL、有效的 API Key(权限足够)、模型标识符正确、部署环境能访问服务商服务器。再按"检查模型连通性"的红灯定位。
Q2:向量模型连不上? 十有八九是 URL 没换成 /v1/embeddings。重排模型对应 /v1/rerank。
Q3:批量添加后模型一个都用不了? 官方明确"获取到的模型默认是未启用的",需手动点开关启用。
Q4:多模态报错说消息格式不兼容? 见 4.4,检查 content 是数组还是字符串,必要时把模型改为纯文本类型。
Q5:知识库文档一直解析中? 与向量模型有关:确认已配置向量模型且连通性为 🟢;官方文档说明向量模型配置影响知识库稳定运行。
Q6:模型管理菜单看不到? 用超管登录了。超管只做权限管理,换租户管理员登录。
七、总结
Nexent 的模型配置不是一段 YAML,而是一组界面表单:单个模型只有模型名称、展示名称、模型 URL、API Key 四项,配合 8 类模型类型与 9 个系统槽位;批量拉取的模型默认未启用,必须手动开开关;最终用"检查模型连通性"的蓝/红/绿三色圆点验收。最容易填错的是 URL 后缀------大语言与多模态用 /v1,向量用 /v1/embeddings,重排用 /v1/rerank,而多模态只是共用 Key 和 URL、换个模型名。常见的流式输出、超时重试、用量成本三项诉求,在模型配置页并没有对应开关:流式是运行时 SSE 行为,超时是沙箱级 NEXENT_SANDBOX_TIMEOUT_S,用量成本要看厂商控制台与可选 monitoring 观测组件。把这三项如实落到真实位置,比编造字段名更能让读者照着做通。文中所有【待实测填写】与截图采集步骤,需要你用自己的账号、自己的 Key、自己的调用记录补齐,AI 不能替你做这一步。
边界也要讲明:本文描述的是平台内置的模型配置表单,不适用于自行接入的模型网关或私有协议服务。URL 后缀由服务商的 OpenAI 兼容实现决定,换厂商时先在其文档里确认;超时与重试属于运行时和沙箱层,用量与成本以服务商控制台账单为准,平台内的观测组件只是辅助。版本升级后槽位名称可能调整,发布前对照官方模型配置页复核一次。
参考资料
- Nexent 仓库(AtomGit):https://atomgit.com/ModelEngine/nexent
- Nexent 官方文档 · 模型配置:https://modelengine-group.github.io/nexent/zh/user-guide/agent-development/model-configuration.html
- Nexent 官方文档 · 基于 Docker 安装部署(监控配置):https://modelengine-group.github.io/nexent/zh/quick-start/installation.html
- Nexent 官方文档 · 常见问题:https://modelengine-group.github.io/nexent/zh/quick-start/faq.html
- Nexent 官方文档 · 项目概览(异步与 SSE 流式处理):https://modelengine-group.github.io/nexent/zh/getting-started/overview.html
- Nexent 用户指南 · 首页(账号准备):https://modelengine-group.github.io/nexent/zh/user-guide/home-page.html