llm-nlu-server

llm-nlu-server 是面向 callflow / callout 业务的统一 NLU HTTP 服务，对外提供 decision（路由决策）和 extract（字段抽取）能力，内部默认调用 Ollama Chat API。 调用方只依赖稳定的 action / profile 契约，不直接绑定具体模型和 prompt。

专题导航

• 配置与鉴权
• API 参考
• Profiles 与可靠性设计
• 流程脚本与 NLU profile 开发
• 全仓服务目录

运行命令

在仓库根目录：

bun run dev:llm-nlu

或进入本目录：

bun run dev
bun run start
bun run typecheck
bun test
bun run build
bun run build:all

build 在类型检查后构建 Windows x64 独立可执行文件；build:all 构建 Windows 与 Linux x64，并复制外置 config.json 到 dist/。

配置

开发态默认读取当前工作目录下的 config.json；独立可执行文件优先读取自身同目录配置； LLM_NLU_CONFIG_PATH 可显式覆盖路径。最小联调需配置：

• server.host / port / authToken
• llm.ollamaUrl / model / timeoutMs
• logging
• usageRecording

环境变量、日志隐私、使用记录和 token 规则见配置与鉴权。 默认监听与健康检查见服务目录。

最小请求

先确认 Ollama 已运行并拉取 config.json 中 llm.model 指定的模型，然后启动 NLU 服务。 健康检查无需鉴权：

curl http://127.0.0.1:9930/health

默认配置启用内部 token，最小 decision 请求为：

curl -s -X POST http://127.0.0.1:9930/api/v1/nlu \
  -H "Content-Type: application/json" \
  -H "X-Callout-Internal-Token: nlu-token" \
  -d '{
    "action":"decision",
    "profile":"sales-intent",
    "text":"可以，你简单介绍一下",
    "branches":[
      {"key":"interested","desc":"愿意继续沟通"},
      {"key":"reject","desc":"拒绝或不方便"}
    ]
  }'

响应使用 { "ok": true, "data": ... } 或 { "ok": false, "error": "..." } 信封。 extract 请求、能力发现和完整响应结构见API 参考。

鉴权

鉴权头、token 列表、环境变量覆盖和无需鉴权的端点见 配置与鉴权。

接口

• GET /health：进程健康检查。
• GET /api/v1/nlu/capabilities：action 与 profile 能力发现。
• POST /api/v1/nlu：decision 或 extract。

契约唯一来源为API 参考。

内置 profiles

当前 decision / extract profile、注册位置和新增后需重启的约定见 Profiles 与可靠性设计。

小模型可靠性设计

结构化输出 Schema、reason 先行、非法结果兜底与否定语境处理见 Profiles 与可靠性设计。

验证

bun run typecheck
bun test

启动后验证健康检查、携带 token 的 capabilities，以及 decision / extract 各一个请求。新增或 调整 src/nlu-registry.ts 中的 profile 后必须重启服务。

常见故障

• Ollama 不可达：检查 llm.ollamaUrl 与 Ollama 服务状态。
• 模型不存在：拉取 llm.model 指定模型或改为本机已有模型。
• 401：校准 server.authToken 与 X-Callout-Internal-Token。
• profile 不存在：访问 capabilities 并确认注册表，修改注册表后重启。
• 使用记录含客户原话和 prompt；不允许落盘时关闭 usageRecording.enabled。

更多跨服务问题见故障排查。任务中启动的服务必须在结束前停止。