快速开始¶
本页面面向调用方。完成以下步骤后，可验证：健康检查、纯检索、完整问答、流式输出、图片隐患识别。
若服务已由他人部署完毕，可直接跳至 第 3 步，将地址替换为对方提供的地址。
1. 配置¶
CG_RAG 的入口脚本为 backend/src/run_cg_rag_http.sh。建议将非密钥配置写入 YAML 文件，API key 则存放于不纳入版本控制的 secrets 文件：
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
路径与上游配置写入 config/question_app.yaml，密钥配置仅写入 question_app.secrets.yaml。各字段的写法见 字段手册。
仅使用检索功能（无需调用模型）时，生成上游字段可留空。若需使用问答功能，YAML 中至少须包含以下配置：
cg_rag:
provider: deepseek # 或 poly / openai_compatible
generation_endpoint: https://example.com/v1/chat/completions
generation_model: your-model
以及 secrets 文件中的 cg_rag.api_key。等价的环境变量写法同样有效：
export CG_RAG_GENERATION_ENDPOINT='https://example.com/v1/chat/completions'
export CG_RAG_GENERATION_MODEL='your-model'
export CG_RAG_API_KEY='server-side-secret'
export CG_RAG_LLM_PROVIDER='deepseek'
如需使用图片识别功能，在 cg_rag.vision 下填写 endpoint / model，密钥写入 cg_rag.vision.api_key（或通过 CG_RAG_VISION_* 环境变量配置）。
检索 profile 的语料、索引、embedding 和 rerank 配置写在 retrieval:（含 usual / usual_plus_law / full），完整字段说明见配置指南与 CG 字段手册。
2. 启动¶
默认地址：
首次启动需加载索引，通常约需一分钟后方可响应请求。
3. 确认服务是否健康¶
{
"ok": true,
"service": "CG_RAG",
"available_scopes": ["full", "usual", "usual_plus_law"],
"active_scope": "full",
"config_issues": [],
"generation": { "configured": true, "provider": "deepseek" },
"vision": { "configured": true }
}
须确认以下四项：ok=true、config_issues 为空、所需 scope 存在于 available_scopes 中、generation.configured=true。如有异常，请参阅故障排查。
响应中不会出现 API key、完整本地路径或上游响应正文，此为预期行为。
4. 只检索，不调用模型¶
curl --noproxy '*' -sS \
-X POST http://127.0.0.1:8864/cg-rag/retrieve-rerank \
-H 'Content-Type: application/json' \
-d '{"query":"脚手架搭设完毕后，验收应当由谁组织？","scope":"usual","topk":3}'
返回 retrieval_docs 数组，已按相关度降序排列：
{
"num_docs": 3,
"retrieval_docs": [
{
"law_name": "DB44-1876-2016轮扣式钢管脚手架安全技术规程",
"article_number": "9.3.5",
"text": "模板支撑架搭设完毕后,应组织相关人员验收,验收合格后方可进入下一工序施工。",
"source": "bm25",
"retrieval_score": 0.9409563541412354
}
],
"cache": { "hit": false, "ttl_seconds": 300.0 }
}
此接口不调用 LLM。首次请求可能需要加载 retriever，后续请求将复用常驻实例。
5. 完整问答¶
curl --noproxy '*' -sS \
-X POST http://127.0.0.1:8864/cg-rag/rag \
-H 'Content-Type: application/json' \
-d '{"query":"脚手架搭设完毕后，验收应当由谁组织？","scope":"usual","topk":5,"max_items":3}'
{
"retrieval": { "num_docs": 5, "retrieval_docs": ["..."] },
"generation": {
"ok": true,
"generation_mode": "constrained",
"answer_text": "我根据在线检索与候选筛选结果，整理出以下最相关条文：\n1. 《建筑施工竹脚手架安全技术规范》（JGJ254-2011）第7.2.3条：竹脚手架应由单位工程负责人组织技术、安全人员进行检查验收。",
"pred_indices": [3],
"usage": { "prompt_tokens": 487, "completion_tokens": 6, "total_tokens": 493 }
}
}
retrieval 为召回与重排结果，generation 为条文选择结果。
HTTP 200 不等于生成成功
检索成功但模型未选出条文时，HTTP 状态码仍为 200，而 generation.ok 为 false。业务代码必须判断 generation.ok。
pred_indices 为 1-based 序号，对应 retrieval.retrieval_docs 中的位置——取文档时使用 docs[i - 1]。
6. 流式输出¶
curl --noproxy '*' -N \
-X POST http://127.0.0.1:8864/cg-rag/rag/stream \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
-H 'X-Request-ID: req_quickstart_001' \
-d '{"query":"施工现场临时用电有哪些关键要求？","scope":"usual_plus_law","topk":20,"max_items":5}'
事件顺序为 progress → retrieval → 若干 token → final。业务失败时会先出现 error 事件，随后仍以结构完整的 final 事件收尾。
客户端须以 final 作为唯一权威终态，不得以接收到最后一个 token 作为结束判断依据。
可运行的解析代码见代码示例。
7. 图片隐患识别¶
首先确认视觉上游已完成配置：
curl --noproxy '*' -sS http://127.0.0.1:8864/cg-rag/health \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["vision"]["configured"])'
图片以 base64 格式传入。base64 命令在不同系统上参数有所差异：
自由生成模式，单次模型调用、不执行检索，通常数秒内返回：
curl --noproxy '*' -sS \
-X POST http://127.0.0.1:8864/cg-rag/vision/answer \
-H 'Content-Type: application/json' \
-d "{\"images\":[{\"data\":\"$IMG\",\"mime_type\":\"image/jpeg\"}]}"
智能生成模式，模型自行检索法规并给出 [cite^n] 引用，通常需要一到三分钟：
curl --noproxy '*' -sS --max-time 600 \
-X POST http://127.0.0.1:8864/cg-rag/vision/agentic \
-H 'Content-Type: application/json' \
-d "{\"images\":[{\"data\":\"$IMG\",\"mime_type\":\"image/jpeg\"}],\"scope\":\"full\",\"topk\":12}"
两者的字段说明、上限、隐患定级口径及错误码见视觉。