配置与鉴权

配置

开发态默认读取当前工作目录下的 config.json。打包成独立可执行文件后，优先读取可执行文件同目录下的 config.json。也可通过 LLM_NLU_CONFIG_PATH 显式指定配置文件路径。

json

{
  "server": {
    "host": "0.0.0.0",
    "port": 9930,
    "authToken": ["nlu-token"]
  },
  "llm": {
    "ollamaUrl": "http://127.0.0.1:11434/api/chat",
    "model": "qwen3.5:2b",
    "timeoutMs": 30000
  },
  "logging": {
    "dir": "logs",
    "level": "info",
    "maxSize": "20m",
    "maxFiles": "14d",
    "detailedContentEnabled": true
  },
  "usageRecording": {
    "enabled": true,
    "dir": "data/usage"
  }
}

配置项：

字段	说明
`server.host`	HTTP 服务监听地址
`server.port`	HTTP 服务监听端口，默认 `9930`
`server.authToken`	内部调用 token 列表；为空数组时不启用鉴权（出厂配置为 `["nlu-token"]`，仅供本地联调）
`llm.ollamaUrl`	Ollama Chat API 地址，默认 `http://127.0.0.1:11434/api/chat`
`llm.model`	模型名称；出厂 `config.json` 为 `qwen3.5:2b`，未配置时代码默认 `qwen2.5:7b`
`llm.timeoutMs`	单次 Ollama 请求超时时间，单位毫秒
`logging.*`	日志目录 / 级别 / 滚动策略与详细内容开关，见下文「日志」
`usageRecording.enabled`	是否按天把每次 NLU 调用的输入、模型 messages、原始输出与最终结果追加到 JSONL（供离线整理微调数据；`outcome` 非 `model` 的行即兜底坏例）。写入异步且不影响主流程
`usageRecording.dir`	JSONL 记录目录，相对进程工作目录，默认 `data/usage`

环境变量优先于配置文件：

环境变量	覆盖字段
`LLM_NLU_CONFIG_PATH`	配置文件路径
`LLM_NLU_HOST`	`server.host`
`LLM_NLU_PORT`	`server.port`
`LLM_NLU_AUTH_TOKEN`	`server.authToken`，支持逗号分隔多个 token
`LLM_NLU_INTERNAL_TOKEN`	`server.authToken` 的兼容别名
`LLM_NLU_OLLAMA_URL`	`llm.ollamaUrl`
`LLM_NLU_MODEL`	`llm.model`
`LLM_NLU_TIMEOUT_MS`	`llm.timeoutMs`
`LLM_NLU_DETAILED_CONTENT_LOG_ENABLED`	`logging.detailedContentEnabled`，支持 `true/false`、`1/0`、`yes/no`、`on/off`
`LLM_NLU_USAGE_RECORDING_ENABLED`	`usageRecording.enabled`，真假值写法同上
`LLM_NLU_USAGE_RECORDING_DIR`	`usageRecording.dir`

日志

服务日志使用单行结构化 JSON，并通过 request、ollama-request、ollama-response、 ollama-error 前缀区分事件；控制台与 logs/application-YYYY-MM-DD.log 输出相同内容，文件按日滚动。logging.dir、level、maxSize、maxFiles 默认分别为 logs、info、 20m、14d，对应环境变量 LLM_NLU_LOG_DIR、LLM_NLU_LOG_LEVEL、 LLM_NLU_LOG_MAX_SIZE、LLM_NLU_LOG_MAX_FILES。

默认开启详细内容日志（logging.detailedContentEnabled=true），记录 NLU HTTP 请求体及最终返回 body、实际发送给 Ollama 的完整 payload，以及 Ollama 原始响应 body 和实际模型 content。生产环境如不希望日志包含客户话术、prompt 或模型原始返回，可设置 logging.detailedContentEnabled=false 或环境变量 LLM_NLU_DETAILED_CONTENT_LOG_ENABLED=false；关闭后仍保留 HTTP method、path、 status、duration、action、profile、模型及错误类型等摘要。

无论开关状态：不记录请求头、内部鉴权 token 或 URL 查询参数；GET /health 不产生访问日志；日志写入失败不会改变 HTTP 响应。

使用记录收集（微调数据）

小模型在部分场景可能表现不佳，需要基于真实使用数据微调。开启 usageRecording.enabled （默认开启）后，每次 POST /api/v1/nlu 执行都会把一条完整使用记录追加到 <usageRecording.dir>/nlu-usage-YYYY-MM-DD.jsonl（按本地日期滚动，与运行日志口径一致），一行一个 JSON 对象：

字段	说明
`timestamp`	记录生成时间，ISO 8601（UTC）
`action` / `profile` / `model`	实际命中的能力、profile 与模型（含 profile 级覆盖）
`durationMs`	从发起模型调用到得出最终结果的耗时（毫秒）
`outcome`	结果来源：`model`（模型直出）、`fallback-error`（Ollama 调用失败）、`fallback-invalid-key`（decision 返回非法分支 key）、`fallback-invalid-fields`（extract 未返回 fields 对象）
`input`	已通过校验的原始请求输入（text、branches/fields 等）
`messages`	实际发送给模型的 system/user 消息，可直接作为微调样本的输入侧
`modelOutput`	模型返回并解析成功的原始 JSON；调用失败时为 `null`
`error`	走兜底时的错误描述（仅兜底记录存在）
`fallbackFieldKeys`	extract 模型直出但漏掉、由兜底值补齐的字段 key 列表（仅发生时存在）
`result`	最终返回给调用方的结果

后处理建议：outcome 为 model 的行经人工或规则复核后可作为微调正样本（messages + modelOutput/result 即一条 chat 样本）；outcome 非 model 或带 fallbackFieldKeys 的行就是模型失守案例，先分析是否合理，合理的补上人工标注答案后并入微调集。

注意事项：

记录包含客户原话、prompt 与模型输出，且不受 logging.detailedContentEnabled 开关影响；不希望落盘时把 usageRecording.enabled 设为 false（或环境变量 LLM_NLU_USAGE_RECORDING_ENABLED=false）。
写入异步串行进行，收集设施故障只产生 usage_record_write_failed 日志，不影响 NLU 响应。
记录文件不会自动清理，纳入微调集后请自行归档；data/ 目录已加入 .gitignore，不要提交到仓库。

鉴权

server.authToken 为空时，/api/v1/nlu/capabilities 与 /api/v1/nlu 不做 token 校验。
server.authToken 非空时，请求头 X-Callout-Internal-Token 必须命中其中一个 token。
GET /health 不做鉴权，用于本地和运维健康检查。

配置与鉴权 ​

配置 ​

日志 ​

使用记录收集（微调数据） ​

鉴权 ​

配置与鉴权

配置

日志

使用记录收集（微调数据）

鉴权