CG_RAG 配置

CG_RAG 优先读取 CG_RAG_* 环境变量。未设置时，部分字段会回退到历史 QUESTION_GENERATED_APP_* 名称，便于现有部署平滑迁移。

远端部署也支持 YAML 配置入口：启动脚本会读取 QUESTION_APP_CONFIG 和 QUESTION_APP_SECRETS_CONFIG，再由 config_yaml print-shell 映射为下方环境变量。推荐把非密钥运行配置放在 question_app.remote.yaml，把 API key 等敏感信息放在不入库的 question_app.secrets.yaml。

路由

变量	默认值	说明
CG_RAG_HTTP_PREFIX	/cg-rag	HTTP API 路由前缀
CG_RAG_MCP_PATH	/cg-rag/mcp	Streamable HTTP MCP 挂载路径

默认入口：

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

检索范围

可用 scope：

scope	含义
full	全库
usual	常用规范
usual_plus_law	常用规范 + 常用法律

HTTP/MCP 请求省略 scope 时当前按请求模型回退到 usual。生产集成建议显式传入目标 scope，避免默认值差异影响结果。

生成配置

变量	默认值	说明
CG_RAG_LLM_PROVIDER	deepseek	生成接口 provider；支持 deepseek、poly、openai_compatible
CG_RAG_GENERATION_ENDPOINT	空	OpenAI-compatible chat completions 地址
CG_RAG_GENERATION_MODEL	空	生成模型名
CG_RAG_API_KEY	空	生成接口鉴权 token；配置后以 Bearer token 发送
CG_RAG_GENERATION_RESPONSE_FORMAT_JSON	true	是否请求 JSON response format
CG_RAG_GENERATION_ENABLE_THINKING	false	服务级 thinking 默认值；请求体中的 generation_enable_thinking 可单次覆盖
CG_RAG_GENERATION_STREAMING	true	constrained generation 是否以 OpenAI-compatible stream 方式读取 LLM 输出
CG_RAG_STREAM_ANSWER_TOKEN_DELAY_SECONDS	0.025	/rag/stream 发送最终 answer token 的 pacing 间隔；设为 0 关闭延迟
CG_RAG_TIMEOUT_SECONDS	120	LLM 请求超时时间
CG_RAG_MAX_CONTEXT_DOCS	78	constrained generation 最多使用的候选文档数
CG_RAG_DEFAULT_MAX_ITEMS	10	默认最多返回条文数

CG_RAG_GENERATION_ENDPOINT 和 CG_RAG_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。

视觉识别配置

视觉隐患识别需要一个多模态上游。它与上面的文本生成配置相互独立：多数部署把文本生成指向 DeepSeek，把视觉指向自建或第三方 VLM 网关。

变量	默认值	说明
CG_RAG_VISION_ENDPOINT	空	多模态 OpenAI-compatible chat completions 地址
CG_RAG_VISION_MODEL	空	视觉模型名
CG_RAG_VISION_API_KEY	空	视觉接口鉴权 token；留空时回退到 CG_RAG_API_KEY
CG_RAG_VISION_ENABLE_THINKING	false	服务级 thinking 默认值；请求体中的 enable_thinking 可单次覆盖
CG_RAG_VISION_STREAMING	true	是否以 stream 方式读取 VLM 输出
CG_RAG_VISION_MAX_IMAGES	4	单次请求最多图片数
CG_RAG_VISION_MAX_IMAGE_BYTES	8388608	单张图片解码后的字节上限
CG_RAG_VISION_MAX_TOKENS	4096	视觉生成的 max_tokens
CG_RAG_VISION_AGENTIC_MAX_SEARCH_ROUNDS	3	智能生成最多检索轮数，硬上限为 3
CG_RAG_VISION_AGENTIC_RETRIEVAL_TOPK	12	智能生成每轮检索候选数

CG_RAG_VISION_ENDPOINT 或 CG_RAG_VISION_MODEL 未配置时，只有 /cg-rag/vision/* 返回 vision_not_configured；检索和文本生成完全不受影响。用 /cg-rag/health 的 vision.configured 做能力发现。

视觉调用与文本 constrained generation 共用同一个 generation 容量限制器（CG_RAG_GENERATION_CONCURRENCY）。视觉请求耗时远高于文本生成，批量视觉流量会挤占文本生成配额，必要时应为两类流量分开部署实例。

智能生成的检索走进程内调用，因此它复用同一份 retrieve cache、profile fingerprint 和 CG_RAG_RETRIEVAL_CONCURRENCY，不额外占用 HTTP 或 MCP 连接。

远端 Embedding 和 Rerank

变量	默认值	说明
CG_RAG_EMBEDDING_API_ENDPOINT	空	可选远端 embedding API
CG_RAG_EMBEDDING_API_MODEL	qwen3-embedding	可选远端 embedding 模型名
CG_RAG_EMBEDDING_API_DIMENSION	按服务配置	可选远端 embedding 维度
CG_RAG_RERANK_API_ENDPOINT	空	可选远端 rerank API
CG_RAG_RERANK_API_MODEL	qwen-rerank	可选远端 rerank 模型名

未配置远端 rerank API 时，服务使用本地 reranker 配置。健康检查中的 rerank.api_enabled 可用于确认当前是否启用远端 rerank。

Retrieve-Rerank 缓存

变量	默认值	说明
CG_RAG_RETRIEVE_CACHE_MAX_ENTRIES	128	retrieve-rerank 内存缓存最大条目数；0 禁用写入
CG_RAG_RETRIEVE_CACHE_TTL_SECONDS	300	retrieve-rerank 内存缓存 TTL 秒数；0 禁用写入

缓存 key 包含 normalized scope、去首尾空白后的 query、topk 和 profile_fingerprint。profile_fingerprint 由当前 scope 的语料/索引文件摘要、embedding 配置、rerank 配置和 profile 关键字段计算；索引文件、远端 embedding/rerank 模型或 profile 配置变化后，旧缓存不会被误用。缓存只覆盖 retrieve-rerank 结果，不缓存 LLM generation。

健康检查和 retrieve-rerank 响应会暴露脱敏后的 fingerprint 摘要：

• GET /cg-rag/health：profile_fingerprint.id 和 profile_fingerprint.summary。
• POST /cg-rag/retrieve-rerank：顶层 profile_fingerprint、profile_fingerprint_summary，以及 pipeline.profile_fingerprint。
• 缓存命中：cache.hit: true，并保留 cached_pipeline 便于比较命中时的原始 pipeline 摘要。

Hydration Sidecar

变量	默认值	说明
CG_RAG_HYDRATION_SIDECAR_ENABLED	true	是否启用 SQLite hydration sidecar
CG_RAG_HYDRATION_SIDECAR_PATH	空	hydration SQLite 路径；为空时落到应用 cache 目录

hydration sidecar 用于补全/缓存 corpus 文档字段，减少运行时重复解析开销。健康检查中的 hydration 会报告 indexed_corpora、lookup_hits、lookup_misses、lookup_failures、last_error 和 build_count。

容量控制

变量	默认值	说明
CG_RAG_RETRIEVAL_CONCURRENCY	16	同时进入 retrieve-rerank 的最大请求数
CG_RAG_GENERATION_CONCURRENCY	16	同时占用生成 provider 的最大请求数
CG_RAG_CAPACITY_WAIT_TIMEOUT_SECONDS	5	等待容量的最长时间；超时后返回 capacity.exceeded

检索与生成使用独立 limiter，避免慢生成耗尽检索容量。完整 RAG 会依次获取所需容量，不会在等待 generation 时继续占用 retrieval limiter。健康检查的 capacity 字段包含各 limiter 的 max、active、queued、rejected、peak 和等待上限。

YAML 配置示例

YAML 配置会映射到同名环境变量，适合远端部署时减少长命令行环境变量：

cg_rag:
  provider: deepseek
  host: 0.0.0.0
  port: 8864
  warmup_scopes: full
  remote_api: true
  mcp_url: http://127.0.0.1:8864/cg-rag/mcp/
  generation_streaming: true
  generation_endpoint: https://api.deepseek.com/chat/completions
  generation_model: deepseek-v4-flash
  generation_response_format_json: true
  generation_enable_thinking: false
  retrieval_concurrency: 16
  generation_concurrency: 16
  capacity_wait_timeout_seconds: 5
  timeout_seconds: 180

retrieval:
  default_scope: full
  embedding_api:
    endpoint: https://example.com/v1/embeddings
    model: qwen3-embedding
    dimension: 2560
  rerank_api:
    endpoint: https://example.com/v1/rerank
    model: qwen-rerank

question_app.secrets.yaml 的字段结构见仓库 example。真实值应由 Secret 管理系统写入部署机上的 0600 文件；不要在文档、命令行、shell history 或 git 中粘贴 credential。

Warmup

如果使用仓库中的 CG_RAG 启动脚本，常用运行时变量如下：

变量	默认值	说明
QUESTION_APP_CG_RAG_HOST	0.0.0.0	HTTP/MCP 监听地址
QUESTION_APP_CG_RAG_PORT	8864	HTTP/MCP 监听端口
QUESTION_APP_CG_RAG_WARMUP_SCOPES	full	启动后等待并预热的 scope 列表；空字符串表示跳过
QUESTION_APP_CG_RAG_STARTUP_TIMEOUT_SECONDS	300	启动健康检查和 warmup 等待时间

POST /cg-rag/warmup 会顺序加载 scopes，但 retriever manager 同时只保留一个 active profile。传入多个 scope 时，最后一个 scope 会成为最终 resident scope。

历史部署配置可能从 QUESTION_APP_STREAMING_ENABLED 映射 generation streaming；显式设置 CG_RAG_GENERATION_STREAMING 时以 CG_RAG 自己的设置为准。

编排边界

CG_RAG 编排不包含 domain gate。服务只负责：

1. retrieve；
2. rerank；
3. 可选 constrained generation；
4. 可选视觉隐患识别（自由生成与智能生成）。

调用方如需领域判断、权限控制、用户画像或业务审计，应在调用 CG_RAG 前后自行编排。视觉接口同样不做附件存储、会话状态或用户归属管理：图片随请求传入、在内存中处理、随响应结束释放。