字段手册：CG_RAG¶

供部署 CG 进程的运维人员参阅，调用方无需阅读。字段格式与加载顺序见字段手册总览。

本章说明 question_app.yaml（或 cg-retrieval.yaml）中 cg_rag: 与 retrieval: 的配置项。修改后须重启 CG 进程。

未配置 generation_endpoint / generation_model 时，检索功能仍可正常使用；rag / constrained-generate 接口将返回业务层失败，而非 HTTP 500。

`cg_rag`¶

CG_RAG HTTP/MCP 进程。生产环境中可将此段（连同 retrieval）单独提取至 cg-retrieval.yaml。

YAML 键	值格式	环境变量	含义
`http_prefix`	以 `/` 开头，如 `/cg-rag`	`CG_RAG_HTTP_PREFIX`	HTTP 路由前缀
`mcp_path`	如 `/cg-rag/mcp`	`CG_RAG_MCP_PATH`	MCP 挂载路径
`mcp_url`	完整 URL，建议带尾 `/`	`QUESTION_GENERATED_APP_CG_RAG_MCP_URL`	MCP 对外地址
`provider`	`deepseek` / `poly` / `openai_compatible`	`CG_RAG_LLM_PROVIDER`	文本生成 provider
`generation_endpoint`	chat completions URL	`CG_RAG_GENERATION_ENDPOINT`	文本生成上游
`generation_model`	上游模型名	`CG_RAG_GENERATION_MODEL`	文本生成模型
`api_key`	仅写入 secrets	`CG_RAG_API_KEY`	文本生成鉴权
`generation_response_format_json`	`true` / `false`	`CG_RAG_GENERATION_RESPONSE_FORMAT_JSON`	JSON response format
`generation_enable_thinking`	`true` / `false`	`CG_RAG_GENERATION_ENABLE_THINKING`	服务级 thinking 默认值
`generation_streaming`	`true` / `false`	`CG_RAG_GENERATION_STREAMING`	constrained generation 是否以 stream 方式读取上游
`stream_answer_token_delay_seconds`	小数，`0` 表示关闭	`CG_RAG_STREAM_ANSWER_TOKEN_DELAY_SECONDS`	`/rag/stream` token pacing
`timeout_seconds`	正整数，单位秒	`CG_RAG_TIMEOUT_SECONDS`	LLM 超时时限
`max_context_docs`	正整数	`CG_RAG_MAX_CONTEXT_DOCS`	生成阶段最多使用的候选文档数
`default_max_items`	正整数	`CG_RAG_DEFAULT_MAX_ITEMS`	默认返回条文数
`cache_max_entries`	整数，`0` 表示禁用写入	`CG_RAG_RETRIEVE_CACHE_MAX_ENTRIES`	retrieve-rerank 缓存条数
`cache_ttl_seconds`	秒，`0` 表示禁用写入	`CG_RAG_RETRIEVE_CACHE_TTL_SECONDS`	缓存 TTL
`hydration_sidecar_enabled`	`true` / `false`	`CG_RAG_HYDRATION_SIDECAR_ENABLED`	hydration sidecar
`hydration_sidecar_path`	绝对路径或空字符串	`CG_RAG_HYDRATION_SIDECAR_PATH`	sidecar SQLite 路径
`generation_concurrency`	正整数	`CG_RAG_GENERATION_CONCURRENCY`	生成并发数（与视觉共用）
`retrieval_concurrency`	正整数	`CG_RAG_RETRIEVAL_CONCURRENCY`	检索并发数
`capacity_wait_timeout_seconds`	秒	`CG_RAG_CAPACITY_WAIT_TIMEOUT_SECONDS`	等待容量的超时时限
`vision_max_pixels`	正整数	`CG_RAG_VISION_MAX_PIXELS`	图片像素上限
`vision_max_dimension`	正整数	`CG_RAG_VISION_MAX_DIMENSION`	长边上限
`vision_normalized_max_dimension`	正整数	`CG_RAG_VISION_NORMALIZED_MAX_DIMENSION`	规范化后长边上限
`vision_jpeg_quality`	`1`–`100`	`CG_RAG_VISION_JPEG_QUALITY`	JPEG 质量
`remote_api`	`true` / `false`	`CG_RAG_REMOTE_API`	是否作为远端 API 进程运行
`host`	`0.0.0.0`	`QUESTION_APP_CG_RAG_HOST`	监听地址
`port`	整数，默认 `8864`	`QUESTION_APP_CG_RAG_PORT`、`CG_RAG_PORT`	监听端口
`visible_gpu`	字符串，可为 `""`	`QUESTION_APP_CG_RAG_VISIBLE_GPU`	`CUDA_VISIBLE_DEVICES`
`tmux_window`	字符串	`QUESTION_APP_CG_RAG_TMUX_WINDOW`	启动脚本 tmux 窗口名
`legacy_windows`	逗号分隔或空字符串	`QUESTION_APP_CG_RAG_LEGACY_WINDOWS`	需关闭的旧窗口列表
`warmup_scopes`	`full` 或 `full,usual`	`QUESTION_APP_CG_RAG_WARMUP_SCOPES`、`CG_RAG_WARMUP_SCOPES`	启动预热；空字符串表示跳过
`startup_timeout_seconds`	正整数	`QUESTION_APP_CG_RAG_STARTUP_TIMEOUT_SECONDS`	启动等待时限

`cg_rag.vision`¶

嵌套于 cg_rag: 下，与文本生成上游相互独立。

YAML 键	值格式	环境变量	含义
`endpoint`	多模态 chat completions URL	`CG_RAG_VISION_ENDPOINT`	VLM 地址；为空则视觉未配置
`model`	上游模型名	`CG_RAG_VISION_MODEL`	VLM 模型名
`api_key`	仅写入 secrets	`CG_RAG_VISION_API_KEY`	为空则回退至 `CG_RAG_API_KEY`
`enable_thinking`	`true` / `false`	`CG_RAG_VISION_ENABLE_THINKING`	服务级视觉 thinking 默认值
`streaming`	`true` / `false`	`CG_RAG_VISION_STREAMING`	是否以 stream 方式读取 VLM
`max_images`	正整数，默认 `4`	`CG_RAG_VISION_MAX_IMAGES`	单次请求最多图片数
`max_image_bytes`	字节数	`CG_RAG_VISION_MAX_IMAGE_BYTES`	单张图片解码后的大小上限
`max_tokens`	正整数	`CG_RAG_VISION_MAX_TOKENS`	视觉请求的 max_tokens
`agentic_max_search_rounds`	正整数，硬上限 `3`	`CG_RAG_VISION_AGENTIC_MAX_SEARCH_ROUNDS`	智能生成检索轮数
`agentic_retrieval_topk`	正整数	`CG_RAG_VISION_AGENTIC_RETRIEVAL_TOPK`	每轮检索候选数
`agentic_workflow`	`controller` / `continuous`	`CG_RAG_VISION_AGENTIC_WORKFLOW`	智能生成工作流；默认 controller。如需恢复原生 ReAct，设为 `continuous`
`profile`	`e10` / `continuous_base` / `controller` / `controller_wip`	`CG_RAG_VISION_PROFILE`	命名行为包。为空时：`continuous` 对应 `e10`，其余对应 `controller`。修改后须重启 CG
`total_budget_seconds`	正数，单位秒；`0` 或空表示使用 profile 默认值	`CG_RAG_VISION_TOTAL_BUDGET_SECONDS`	整单墙钟预算。阶段启动前检查；预算耗尽且无可用报告时返回 `vision_budget_exceeded`。e10 默认 150s（现网均时约 67s，Question/CG 外层超时 180s，取中间值以保留重试余量）。修改后须重启 CG
`sse_heartbeat_seconds`	`≥0`；`-1` 或未设表示使用 profile 值；`0` 表示关闭	`CG_RAG_VISION_SSE_HEARTBEAT_SECONDS`	等待 VLM/检索时长阶段的 SSE 心跳。默认 15s：发送 `: keepalive` 注释行（前端 `web/src/lib/sse.ts` 忽略）并附带 `progress`+`heartbeat` 事件。修改后须重启 CG
`strict_retrieval_failure`	`true`/`false`；空表示使用 profile 值	`CG_RAG_VISION_STRICT_RETRIEVAL_FAILURE`	检索全部失败时是否在成文前拒绝。e10/controller 默认开启；`continuous_base` 默认关闭（与线上旧有的「先成文」行为一致）。如需回退，设为 `false` 或切换至 `continuous_base`。修改后须重启 CG
`upstream_retry_count`	正整数；`0` 或空表示使用 profile 默认值	`CG_RAG_VISION_UPSTREAM_RETRY_COUNT`	VLM/上游 connect 与 pre-token 重试次数（profile 默认值多为 4）。修改后须重启 CG
`upstream_retry_sleep_seconds`	`≥0`；`-1` 或未设表示使用 profile 值	`CG_RAG_VISION_UPSTREAM_RETRY_SLEEP_SECONDS`	上游重试间隔，单位秒。修改后须重启 CG
`hybrid_generation_endpoint`	chat completions URL	`CG_RAG_HYBRID_GENERATION_ENDPOINT`	垂域+RAG 的文本模型地址。为空则 `/vision/hybrid` 不可用
`hybrid_generation_model`	上游模型名	`CG_RAG_HYBRID_GENERATION_MODEL`	现网为 `deepseek-flash`。请勿填写受约束生成所用的 `deepseek-chat`
`hybrid_generation_api_key`	仅写入 secrets	`CG_RAG_HYBRID_GENERATION_API_KEY`	文本模型密钥，不回退至 `CG_RAG_API_KEY`

Prompt SHA 钉扎见各 profile 的 prompt_keys；启动预检由 CG_RAG_STRICT_PROMPT_PINS 控制（严格模式下 pin 不匹配时拒绝启动）。

endpoint 或 model 为空时，仅 /cg-rag/vision/* 接口返回 vision_not_configured。亦可使用遗留写法，将 CG_RAG_VISION_* 写在 cg_rag.env 或顶层 env: 中；推荐使用 typed vision: 段，语义更清晰。

密钥字段结构见问答主站 · secrets。

`retrieval`¶

未按 scope 覆盖时使用的默认检索路径，以及 Question API 调用检索 HTTP 的地址。问答进程同样会读取 default_scope 和 retriever_*，路径表仍置于本段，因为修改后必须重启 CG。

YAML 键	值格式	环境变量	含义
`default_scope`	`full` / `usual` / `usual_plus_law`	`QUESTION_GENERATED_APP_DEFAULT_SCOPE`	默认 scope
`retriever_host`	主机名	`QUESTION_GENERATED_APP_RETRIEVER_HOST`	检索进程主机
`retriever_port`	整数	`QUESTION_GENERATED_APP_RETRIEVER_PORT`	检索端口
`retrieval_endpoint`	完整 URL	`QUESTION_GENERATED_APP_RETRIEVAL_ENDPOINT`	如 `http://127.0.0.1:8864/retrieve`
`corpus_root`	绝对路径	`QUESTION_GENERATED_APP_CORPUS_ROOT`	默认语料路径
`index_root`	绝对路径	`QUESTION_GENERATED_APP_INDEX_ROOT`	默认 dense 索引目录
`bm25_index_root`	绝对路径	`QUESTION_GENERATED_APP_BM25_INDEX_ROOT`	默认 BM25 索引目录
`embedding_model_path`	绝对路径	`QUESTION_GENERATED_APP_EMBEDDING_MODEL_PATH`	本地 embedding 权重路径
`retrieval_method`	如 `qwen3-0.6b` / `qwen3-4b`	`QUESTION_GENERATED_APP_RETRIEVAL_METHOD`	检索方法名
`index_file_name`	如 `qwen3-4b_Flat.index`	`QUESTION_GENERATED_APP_INDEX_FILE_NAME`	dense 索引文件名
`rerank_model_path`	绝对路径	`QUESTION_GENERATED_APP_RERANK_MODEL_PATH`	本地 rerank 权重路径
`topks_by_stem`	映射或 `stem:n,stem:n`	`QUESTION_GENERATED_APP_TOPKS_BY_STEM`	按语料 stem 设定的 topk

scope 仅允许上述三个名称，不支持在 YAML 中新增第四个；如需变更名称列表，须同步修改 Python 代码与前端。

`retrieval.usual` / `usual_plus_law` / `full`¶

每个 scope 对应独立配置段，键名相同，环境变量前缀各异：

YAML 键	`usual` →	`usual_plus_law` →	`full` →
`corpus_root`	`QUESTION_GENERATED_APP_USUAL_CORPUS_ROOT`	`QUESTION_GENERATED_APP_USUAL_PLUS_LAW_CORPUS_ROOT`	`QUESTION_GENERATED_APP_FULL_CORPUS_ROOT`
`index_root`	`…_USUAL_INDEX_ROOT`	`…_USUAL_PLUS_LAW_INDEX_ROOT`	`…_FULL_INDEX_ROOT`
`bm25_index_root`	`…_USUAL_BM25_INDEX_ROOT`	`…_USUAL_PLUS_LAW_BM25_INDEX_ROOT`	`…_FULL_BM25_INDEX_ROOT`
`retrieval_method`	`…_USUAL_RETRIEVAL_METHOD`	`…_USUAL_PLUS_LAW_RETRIEVAL_METHOD`	`…_FULL_RETRIEVAL_METHOD`
`index_file_name`	`…_USUAL_INDEX_FILE_NAME`	`…_USUAL_PLUS_LAW_INDEX_FILE_NAME`	`…_FULL_INDEX_FILE_NAME`
`topks_by_stem`	`…_USUAL_TOPKS_BY_STEM`	`…_USUAL_PLUS_LAW_TOPKS_BY_STEM`	`…_FULL_TOPKS_BY_STEM`

路径必须指向对应 scope 的实际语料与索引。retrieval_method 与 index_file_name 须与构建索引时所用配置保持一致，否则将导致加载失败或召回结果为空。

`retrieval.embedding_api` / `retrieval.rerank_api`¶

YAML 路径	值格式	环境变量	含义
`embedding_api.endpoint`	URL 或 `""`	`CG_RAG_EMBEDDING_API_ENDPOINT`	为空则使用本地 embedding
`embedding_api.model`	模型名	`CG_RAG_EMBEDDING_API_MODEL`	远端 embedding 模型
`embedding_api.dimension`	整数，未使用远端时可填 `0`	`CG_RAG_EMBEDDING_API_DIMENSION`	向量维度
`rerank_api.endpoint`	URL 或 `""`	`CG_RAG_RERANK_API_ENDPOINT`	为空则使用本地 rerank
`rerank_api.model`	模型名	`CG_RAG_RERANK_API_MODEL`	远端 rerank 模型

`env:` 逃生舱¶

任意 KEY: value 键值对，KEY 须为合法环境变量名（字母/数字/下划线）。仅用于尚无对应 typed 字段的项，例如历史部署中的 CG_RAG_VISION_ENDPOINT。已有 typed 字段的配置项请写在对应段，避免两处同时填写导致冲突。

最小可运行片段¶

仅需检索、无需生成时，CG 进程最少须配置 scope 路径：

retrieval:
  default_scope: full
  full:
    corpus_root: /srv/corpora/full
    index_root: /srv/indexes/full-dense
    bm25_index_root: /srv/indexes/full-bm25
    retrieval_method: qwen3-4b
    index_file_name: qwen3-4b_Flat.index
cg_rag:
  host: 0.0.0.0
  port: 8864
  http_prefix: /cg-rag
  mcp_path: /cg-rag/mcp

若需问答功能，在此基础上补充 cg_rag.generation_endpoint / generation_model 及 secrets 中的 cg_rag.api_key。若需图片处理，补充 cg_rag.vision.endpoint / model。

修改 YAML 后重启 CG。以 /cg-rag/health 接口做脱敏确认，禁止在日志中输出 secrets。

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"。

字段手册：CG_RAG¶

cg_rag¶

cg_rag.vision¶

retrieval¶

retrieval.usual / usual_plus_law / full¶

retrieval.embedding_api / retrieval.rerank_api¶

env: 逃生舱¶