Nexent 模型配置:4 字段与 9 个槽位

摘要

摘要 :常见的错误写法是照搬一段 YAML:provider.type: openai、apiKey、baseURL,还列了 timeout、retry、streaming、cost_observable 四个"参数"。对照官方文档会发现,Nexent 模型配置是界面表单,单个模型只有模型名称、展示名称、模型 URL、API Key 四项,另有 8 类模型类型下拉和 9 个系统模型槽位;所谓超时、重试、流式、成本开关都不在这个页面。本文按官方流程写清"添加单个模型 → 批量添加 → 配置系统槽位 → 检查连通性"的完整操作,给出 7 家服务商的 API Key 获取入口与真实 URL 示例,并把流式输出、超时与重试、用量与成本观察这三项常见诉求落到平台里真实存在的位置。

文章目录

一、为什么模型页找不到这些字段:背景与常见误写

源笔记字段 官方模型配置页是否存在 真实对应
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 次连通性验证)

  1. 点击 "添加模型" 按钮,进入添加模型弹窗;
  2. 点击模型类型下拉框 ,从 8 个选项中选一个:大语言模型 / 向量模型 / 图片理解模型 / 图片生成模型 / 视频理解模型 / 重排模型 / 语音识别模型 / 语音合成模型;
  3. 填写表单:
字段 是否必填 官方说明 示例值
模型名称 必填 请求体中的模型名称,格式通常是 模型系列/模型名字 Qwen/Qwen3-8B、BAAI/bge-m3
展示名称 否 默认与模型名称相同 可留空
模型URL 必填 服务商 API 端点,一般以 /v1 结尾 https://api.siliconflow.cn/v1
API Key 单条未标必填,批量标必填 服务商密钥管理页创建 【待实测填写】
  1. 点击 "连通性验证",系统发送测试请求并返回结果;
  2. 点击 "确定",模型进入可用模型列表。

官方给出的三条注意事项,照抄一遍避免踩坑:

  • 模型名称通常格式为 模型系列/模型名字,例如 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 批量添加模型(注意:拉回来的默认是关的)

  1. 在添加模型弹窗中打开 "批量添加模型开关";
  2. 点击模型提供商下拉框选择服务商;
  3. 选择模型类型(同样是那 8 类);
  4. 输入 API Key(必填);
  5. 点 "获取模型" 批量拉取模型列表;
  6. 手动点开关启用所需模型------官方原文:"获取到的模型默认是未启用的";
  7. 点 "确定" 保存。

这一步是新手最常卡住的地方:拉回来一堆模型却一个都选不了,因为没点启用开关。

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 兼容实现决定,换厂商时先在其文档里确认;超时与重试属于运行时和沙箱层,用量与成本以服务商控制台账单为准,平台内的观测组件只是辅助。版本升级后槽位名称可能调整,发布前对照官方模型配置页复核一次。

参考资料

相关推荐
硅农程序猿16 分钟前
SOC 物理实现: RTL2GDS 系列(二)—Innovus 初始化
人工智能·嵌入式硬件·硬件架构
梦想很大很大24 分钟前
一句“你好”用了 5671 Token:我在 Workrun 中追查 Agent 隐性成本的过程
前端·人工智能·后端
进击的荆棘29 分钟前
MySQL——表的操作
数据库·mysql
诗句藏于尽头31 分钟前
游戏《完美神话》-使用Ai-agent进行修复已停服游戏到本地成功部署以及GM端网页完整教程
人工智能·学习·游戏
依晨照旧35 分钟前
从 MQ 积压查出 4000 个线程:不是泄漏,是事件总线的设计代价
人工智能
英辰朗迪AI获客1 小时前
英辰朗迪GEO知识库第188期:动态渲染站点在AI搜索里成了隐形人
人工智能
硅谷秋水1 小时前
MorphMimic 方法分析
人工智能·机器学习·计算机视觉·机器人
MobotStone2 小时前
AI 能不能越用越会用?从“改答案”到“改进自己”,读懂 RSI
人工智能·算法
jay神2 小时前
基于 YOLOv8 的传送带异物检测系统(Web 版)
前端·人工智能·深度学习·yolo·计算机视觉·计算机毕业设计