配置说明¶

本文面向部署人员，调用方无需阅读。

系统包含三个服务：主站 Web（8862）、问答 API（8863）、CG_RAG（8864）。管理台为独立进程（8865/8866）。

配置文件通常位于仓库 config/ 或 /etc/construction-rag/config/。问答服务使用 question_app.yaml，密钥文件为 question_app.secrets.yaml（chmod 600）。CG_RAG 亦可单独读取仅含 retrieval + cg_rag 字段的 cg-retrieval.yaml。管理台使用 paths.yaml / services.yaml / models.yaml / secrets.yaml。

已通过进程环境变量注入的键，不会被 YAML 覆盖。systemd 若使用 launch_service.py --env-json，将先以该快照替换完整环境表，YAML 仅补充缺失的键。

两份 models.yaml 同名，但并非同一文件

管理台的 models.yaml 仅包含流水线使用的 admin_llm；问答目录包含 providers / models.catalog，两者不得相互覆盖。同目录混放时，须在 question_app.yaml 中指定问答目录，或为问答服务单独设置 QUESTION_APP_CONFIG_DIR。

配置变更后，须重启对应进程：

变更内容	重启目标
检索路径、CG 上游、视觉 VLM	CG（生产单元通常为 `construction-rag-cg`）
问答端口、领域门、主站模型列表	问答 API；如有前端变更还需执行 `next build`
管理台路径、登录、启用检索库指针	管理台

各字段的写法详见字段手册：CG_RAG · 问答主站 · 管理台。

本机初始化时，从模板复制配置文件：

cp config/question_app.yaml.example config/question_app.yaml
cp config/question_app.secrets.yaml.example config/question_app.secrets.yaml
chmod 600 config/question_app.secrets.yaml

不得将 Question API 的 models.yaml.example 覆盖到管理台的 models.yaml。run_cg_rag_http.sh / run_question_generated_api.sh / run_question_generated_web.sh 会自动绑定仓库 config/ 中的文件。如需修改路径，可使用 QUESTION_APP_CONFIG、QUESTION_APP_SECRETS_CONFIG、QUESTION_APP_CONFIG_DIR。兼容旧路径：backend/src/question_app.remote.yaml。

默认入口¶

HTTP: http://127.0.0.1:8864/cg-rag
MCP:  http://127.0.0.1:8864/cg-rag/mcp/

可用 scope：usual（常用规范）、usual_plus_law（常用规范及常用法律）、full（全库）。HTTP/MCP 请求省略 scope 时，当前实现按请求模型回退至 usual。生产环境建议显式传入。

生成和 thinking¶

generation_endpoint 和 generation_model 未配置时，retrieve-rerank 功能仍可正常使用；constrained-generate、rag 和 answer 的生成阶段将返回业务失败，不会将配置缺失包装为 HTTP 500。

thinking payload 按 provider 分流：

provider	thinking 关闭	thinking 开启
`deepseek`	`thinking: {"type": "disabled"}`	`thinking: {"type": "enabled"}`
`poly`	不额外注入 thinking 参数	`chat_template_kwargs: {"enable_thinking": true}`
`openai_compatible`	不额外注入 thinking 参数	`chat_template_kwargs: {"enable_thinking": true}`

CG_RAG 的 poly 与通用 openai_compatible adapter 在 thinking 关闭时不注入 chat_template_kwargs。若某兼容端点要求显式传入 enable_thinking=false，应扩展 provider adapter 并补充协议测试，不得由调用方任意透传模型参数。

DeepSeek 官方 API 建议使用 deepseek-v4-flash 或 deepseek-v4-pro 等 V4 模型名；本项目不再依赖旧的 deepseek-chat / deepseek-reasoner 命名来切换 thinking。

视觉上游在 cg_rag.vision 中配置，不得与文本 generation_endpoint 混用。未配置视觉时，仅 /cg-rag/vision/* 接口失败，其余不受影响。视觉与文本生成共用 generation_concurrency，批量视觉请求会占用文本生成配额。

缓存、容量、warmup¶

retrieve-rerank 的缓存键由 normalized scope、去首尾空白后的 query、topk 和 profile_fingerprint 共同构成。fingerprint 由当前 scope 的语料/索引文件摘要、embedding 配置、rerank 配置及 profile 关键字段计算得出；上述内容发生变化时，旧缓存不会被误用。缓存不覆盖 LLM generation。

健康检查和 retrieve-rerank 响应会暴露脱敏后的 fingerprint 摘要：GET /cg-rag/health 返回 profile_fingerprint.id / summary；缓存命中时 cache.hit: true。

检索与生成使用独立 limiter，完整 RAG 流程在等待 generation 期间不会继续占用 retrieval limiter。非流式请求等待容量超时后返回 HTTP 429；/rag/stream 已开始传输后通过 SSE error + final 事件返回错误，HTTP 状态码仍为 200。

POST /cg-rag/warmup 将按顺序加载 scope，但 retriever manager 同时仅保留一个 active profile。传入多个 scope 时，最后一个将成为最终 resident scope。启动脚本的 warmup_scopes 配置详见 CG 字段手册。

hydration sidecar 负责补全 corpus 文档字段。健康检查中的 hydration 字段报告命中次数和失败次数。

编排边界¶

CG_RAG 不承担 domain gate 职责，仅负责 retrieve、rerank、可选受约束生成及可选视觉隐患识别。领域判断、权限校验、会话管理、附件存储均由调用方处理。图片随请求传入、在内存中处理，随响应结束后释放。

YAML 片段¶

完整字段表见字段手册。以下为 CG 常用配置片段：

cg_rag:
  provider: deepseek
  host: 0.0.0.0
  port: 8864
  warmup_scopes: full
  remote_api: true
  http_prefix: /cg-rag
  mcp_path: /cg-rag/mcp
  generation_endpoint: https://api.deepseek.com/chat/completions
  generation_model: deepseek-v4-flash
  vision:
    endpoint: https://example.com/v1/chat/completions
    model: your-vlm

retrieval:
  default_scope: full

密钥仅写入 question_app.secrets.yaml，权限设为 0600。不得在文档、命令行、shell history 或 git 中包含 credential。

inbound_token / path_ids（2026-09-29）¶

cg_rag.inbound_token（secrets）/ CG_RAG_INBOUND_TOKEN：入站 Bearer 令牌。
cg_rag.expose_docs / CG_RAG_EXPOSE_DOCS：默认 false。
CG_RAG_REQUIRE_INBOUND_AUTH、CG_RAG_STRICT_CONFIG_CONFLICTS：严格启动开关，默认关闭。
health/profiles 中的 path_ids：sha256(os.path.realpath(path))[:16]；测试向量 compute_path_id("/data/x") == "e220a107e93688b1"。

视觉 profile 运行时键¶

完整字段表见 yaml-reference-cg.md · cg_rag.vision。常见覆盖项：

键	环境变量	默认（e10）	重启
`profile`	`CG_RAG_VISION_PROFILE`	（由 workflow 推导为 e10）	CG
`total_budget_seconds`	`CG_RAG_VISION_TOTAL_BUDGET_SECONDS`	150	CG
`sse_heartbeat_seconds`	`CG_RAG_VISION_SSE_HEARTBEAT_SECONDS`	15	CG
`strict_retrieval_failure`	`CG_RAG_VISION_STRICT_RETRIEVAL_FAILURE`	true	CG
`upstream_retry_count`	`CG_RAG_VISION_UPSTREAM_RETRY_COUNT`	4	CG