CG_RAG 配置¶
CG_RAG 优先读取 CG_RAG_* 环境变量。未设置时，部分字段会回退到现有 QUESTION_GENERATED_APP_* 配置，以便同一套运行环境同时服务网页应用和外部 HTTP/MCP 调用。
路由¶
| 变量 | 默认值 | 说明 |
|---|---|---|
CG_RAG_HTTP_PREFIX |
/cg-rag |
HTTP API 路由前缀 |
CG_RAG_MCP_PATH |
/cg-rag/mcp |
Streamable HTTP MCP 挂载路径 |
默认入口：
检索范围¶
可用 scope：
| scope | 含义 |
|---|---|
full |
全库 |
usual |
常用规范 |
usual_plus_law |
常用规范 + 常用法律 |
HTTP/MCP 请求省略 scope 时当前按请求模型回退到 usual。生产集成建议显式传入目标 scope，避免默认值差异影响结果。
生成配置¶
| 变量 | 默认值 | 说明 |
|---|---|---|
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 |
配置可保留；当前 constrained 请求不注入 thinking 模板 |
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。
远端 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。缓存只覆盖 retrieve-rerank 结果，不缓存 LLM generation。
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。
编排边界¶
CG_RAG 编排不包含 domain gate。服务只负责：
- retrieve；
- rerank；
- 可选 constrained generation。
调用方如需领域判断、权限控制、用户画像或业务审计，应在调用 CG_RAG 前后自行编排。