字段手册¶
本页说明各配置章节的适用范围。每个 key 的写法及其对应环境变量，按进程分章查阅，无需在单页内逐项浏览。
缓存、warmup、thinking 等行为的配置方式，参见 配置说明。修改后需重启的进程也在该页说明。
章节选择¶
| 配置对象 | 参考章节 |
|---|---|
| 检索路径、生成上游、视觉 VLM、CG 端口 | CG_RAG |
| 问答 API / 主站 Web / 主站模型下拉框 | 问答主站 |
| 文档库管理台、登录邮件、启用检索库 | 管理台（另一个仓库） |
仅通过 HTTP/MCP 调用服务的接入方无需阅读本手册。
文件和加载顺序¶
| 文件 | 作用 | 读取方 |
|---|---|---|
question_app.yaml |
问答 API、Web、CG_RAG、检索路径、附件 | Question API、CG_RAG、Web 启动脚本 |
models.yaml |
Question API 模型目录（显示名、是否公开、生成模式） | 仅 Question API 的 /api/models |
question_app.secrets.yaml |
API key | 同上，覆盖前两份里的同名键 |
cg-retrieval.yaml（可选） |
只给 CG_RAG 用的精简文件，结构仍是 retrieval + cg_rag |
把 QUESTION_APP_CONFIG 指到它即可 |
环境变量指针：
| 变量 | 作用 |
|---|---|
QUESTION_APP_CONFIG |
主 YAML 的绝对路径 |
QUESTION_APP_SECRETS_CONFIG |
secrets YAML 的绝对路径 |
QUESTION_APP_CONFIG_DIR |
目录；未设 QUESTION_APP_CONFIG 时在该目录查找 question_app.yaml / question_app.secrets.yaml，并加载同目录的 sidecar models.yaml |
未设置上述指针时，run_question_generated_api.sh / run_cg_rag_http.sh / run_question_generated_web.sh 将绑定仓库 config/question_app.yaml（若存在）。
合并顺序：主 YAML → sidecar models.yaml → secrets YAML。已存在于进程环境中的键不会被 YAML 覆盖。launch_service.py --env-json 会先整表替换进程环境，再以「只填空」方式加载 YAML，因此旧的 env.json 启动方式仍然可用。
llm.generation_model 是 CG_RAG / 领域门的默认生成模型，与主站下拉框无关。下拉框仅读取 models.catalog（以及内置模板）。
不要把两份 models.yaml 当成同一个文件
管理台仓库的 config/models.yaml 只有 admin_llm / embedding_api，供离线流水线使用。Question API 的 sidecar 也命名为 models.yaml。若两者置于同一目录（例如 /etc/construction-rag/config/），Question API 会将 admin 那份合并进来——当前无害（没有 models: 段），但绝不要用问答目录覆盖 admin 的 models.yaml。同目录混放时，应将问答目录写入 question_app.yaml 的 providers / models 段，或为 Question API 单独设置 QUESTION_APP_CONFIG_DIR。
取值写法¶
YAML 值先按以下规则转换为字符串，再写入环境变量。
| YAML 类型 | 写法 | 进入环境变量后 |
|---|---|---|
| 布尔 | true / false（不要写 True/yes 以外的花活；代码侧也认 1/0/on/off） |
true / false |
| 整数 / 浮点 | 不带引号：8864、0.7 |
"8864" / "0.7" |
| 字符串 | 普通路径可不加引号；含 :、#、开头空格的须加引号 |
原样 |
| 列表 | - a / - b，或行内 [a, b] |
a,b |
映射（仅 topks_by_stem 这类） |
guobiao: 10 |
guobiao:10（多项用逗号拼） |
| 空 | "" 或省略该键 |
空字符串，或不设该环境变量 |
以下写法应当避免：
- 密钥明文写入
question_app.yaml（应置于 secrets 文件，权限0600）。 - 在
env:中重复已有 typed 字段；typed 段优先，env:仅用于尚无专属字段的键。 - 将 Question API 的模型目录写入
llm:。
仓库根目录提供以下模板：
config/question_app.yaml.example
config/models.yaml.example
config/question_app.secrets.yaml.example
复制后去掉 .example 后缀，密钥文件执行 chmod 600。真实 YAML 已被 .gitignore 排除，不得提交。