Nightingale 如何通过 API 创建和管理 AI 助手的大模型配置

Nightingale 如何通过 API 创建和管理 AI 助手的大模型配置

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale

Nightingale 的 AI 助手依赖一套集中管理的大模型（LLM）配置：模型地址、API Key、模型名和采样参数都存在ai_llm_config表里，助手按配置 ID 引用它们。如果你的目标是通过接口（脚本、CI 或第三方系统）完成"测试连通性 → 创建配置 → 查询 → 更新 → 删除"这一整套操作，API 文档给出的 6 个端点就是全部所需。前提条件是 nightingale center 服务已启动，且调用账号具备 LLM 配置管理权限——API 文档将其表述为管理员权限（auth+admin），路由实现上对应的是auth、user加/ai-config/llm-configs权限检查（见 路由注册 中ai-llm-configs相关行）。

下文命令统一假设：

• <N9E_ADDR>：center 服务的地址加端口（例如http://127.0.0.1:<port>），替换为你的实际部署地址；
• <token>：登录返回的 JWT，用于后续所有请求。

准备：登录并拿到请求 token

curl -s -X POST <N9E_ADDR>/api/n9e/auth/login \ -H 'Content-Type: application/json' \ -d '{"username": "admin", "password": "你的登录密码"}'

username和password是必填字段（登录请求结构见 router_login.go）。两条条件性要求：

• 服务开启验证码时，请求体还需带captchaid和verifyvalue，可先调POST /api/n9e/auth/captcha获取；
• 服务开启 RSA 登录加密时，password需先按服务端公钥加密再提交。

登录成功后，dat字段返回 JWT token。后续所有/api/n9e/ai-llm-config*请求都要在请求头中携带：

AUTH="Authorization: Bearer <token>"

如果服务端启用了固定 token 认证（TokenAuth），也可以改用X-User-Token头传递用户 token，两者在 tokenAuth 中间件 中是并列的鉴权途径。

先不创建配置，直接测试连通性

创建配置前建议先验证模型端点、Key 和模型名是否正确。POST /api/n9e/ai-llm-config/test直接基于你传入的连接参数发起真实请求，配置不必事先存在：

curl -s -X POST <N9E_ADDR>/api/n9e/ai-llm-config/test \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{ "api_type": "openai", "api_url": "https://api.openai.com", "api_key": "sk-你的真实Key", "model": "gpt-4o", "extra_config": { "timeout_seconds": 30, "skip_tls_verify": false, "proxy": "", "custom_headers": {} } }'

（api_url、api_key、model以上面的文档示例值为模板，替换为你自己的。）

探测行为（由 probe.go 实现）：服务端按api_type向对应端点发送一条"Hi"消息，输出上限 512 token。三种api_type的实际请求如下（来自 API 文档）：

文档示例的成功响应：

{ "dat": { "success": true, "duration_ms": 856 }, "err": "" }

success为true即端点、凭据、模型名三者都验证通过。一个值得注意的判定：推理模型（reasoning model）可能把 512 token 全部花在思考上，正文为空且finish_reason=length——这种情况连接仍视为健康，因为探测目的（验证端点/鉴权/模型）已达成；只有响应正常结束（finish_reason=stop）却完全无内容时才会报 "no content"。

失败时文档示例如下：

{ "dat": { "success": false, "duration_ms": 5000 }, "err": "HTTP 401: {\"error\": \"invalid api key\"}" }

注意实现细节：当前路由实现同时会把分类后的错误信息放进dat.error字段（见 aiLLMConfigTest 处理器），错误文案跟随请求头X-Language的语言设置。

创建 LLM 配置

连通性验证通过后创建配置。POST /api/n9e/ai-llm-configs的必填字段是name、api_type、api_url、api_key、model，api_type取值为openai、claude、gemini三种（文档示例）：

curl -s -X POST <N9E_ADDR>/api/n9e/ai-llm-configs \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{ "name": "gpt-4o", "description": "OpenAI GPT-4o", "api_type": "openai", "api_url": "https://api.openai.com", "api_key": "sk-你的真实Key", "model": "gpt-4o", "extra_config": { "timeout_seconds": 60, "temperature": 0.7, "max_tokens": 4096, "custom_headers": { "X-Custom": "value" } }, "enabled": true }'

成功响应返回新配置的 ID（文档示例）：

{ "dat": 1, "err": "" }

两条来自 模型实现 的硬规则，创建前要知道：

• name 全局唯一：重名会返回ai llm config name xxx already exists错误；
• 默认配置：系统中第一条配置自动成为默认（is_default = true）；后续创建或更新时把is_default置为true，会清除其他行上的默认标记，保证默认配置唯一。

extra_config（LLMExtraConfig）各字段及含义见 API 文档：timeout_seconds（请求超时，默认 30 秒）、skip_tls_verify、proxy、custom_headers、custom_params、temperature、max_tokens、context_length，全部可选。

查询配置与 Key 的掩码规则

# 列出全部 curl -s <N9E_ADDR>/api/n9e/ai-llm-configs -H "$AUTH" # 按 ID 查详情 curl -s <N9E_ADDR>/api/n9e/ai-llm-config/1 -H "$AUTH"

列表按 ID 排序；查详情时 ID 不存在返回404（ai llm config not found）。

注意响应中api_key是掩码值而不是明文：保留前 4 位和后 4 位、中间以****替代（例如sk-a****wxyz）；长度不超过 8 位的 Key 整体显示为****（见 MaskAPIKey）。所以从 GET 响应里拿到的 Key 不能当作真实 Key 再用于测试或更新——后文会说明服务端如何处理这种回传。

更新配置

curl -s -X PUT <N9E_ADDR>/api/n9e/ai-llm-config/1 \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{ "name": "gpt-4o", "description": "OpenAI GPT-4o", "api_type": "openai", "api_url": "https://api.openai.com", "api_key": "", "model": "gpt-4o-mini", "enabled": true }'

请求体结构与创建接口一致，校验规则也一致。关于api_key有两条保留原值的路径：

• 文档规则：api_key传空字符串时，保留已有值而不覆盖；
• 实现补充：如果你把 GET 拿到的掩码值原样 PUT 回来，更新处理器 会识别出这是掩码回传，同样保留真实 Key，不会把sk-a****wxyz写进数据库。

只有确实要换 Key 时才传新的明文api_key。改名时依然受 name 唯一性约束。成功响应为{"dat": "", "err": ""}；ID 不存在返回404。

删除配置

curl -s -X DELETE <N9E_ADDR>/api/n9e/ai-llm-config/1 -H "$AUTH"

删除成功响应同样为{"dat": "", "err": ""}，ID 不存在返回404。删除是不可逆操作，执行前确认没有助手还引用该配置的 ID。

把配置接到 AI 助手上

LLM 配置创建后，AI 助手（Agent）通过llm_config_id字段引用它。按 AI Agent API 文档，创建 Agent 时llm_config_id必填且必须大于 0：

curl -s -X POST <N9E_ADDR>/api/n9e/ai-agents \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{ "name": "chat-agent", "use_case": "chat", "llm_config_id": 1, "enabled": true }'

另外，当自动接入的消费者（如默认 chat agent）没有绑定具体LLMConfigId时，会回退使用is_default = true且enabled = true的那条配置（见 AILLMConfigPickDefault）——这就是"第一条配置自动设为默认"这个行为存在的意义。

连接测试失败时怎么读错误

POST /api/n9e/ai-llm-config/test的错误信息按 HTTP 状态分类（分类逻辑见 classifyProbeError），每类都附带服务端响应原文：

边界说明

• api_type目前只支持openai、claude、gemini三种；
• 所有接口都要求登录态与 LLM 配置管理权限，普通无权限账号调用会得到鉴权失败；
• 创建、更新、删除操作都会真实落库并影响所有引用该配置的助手，批量变更前建议先用 test 端点验证、再逐条操作。

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale