跳转至

快速开始

跑完这一页，你会得到：一个能回答施工法规问题的服务、一次纯检索调用、一次完整问答、一次流式输出，以及一次图片隐患识别。

已经有人帮你部署好了服务？跳到 第 3 步，把地址换成对方给你的。

1. 配置

CG_RAG 的入口是 backend/src/run_cg_rag_http.sh。真实 endpoint、API key、模型和索引路径只放在本地环境变量或不入库的 secrets YAML 里。

只用检索（不需要模型）时，这一步可以跳过。要用问答就得配生成上游：

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'   # 或 poly / openai_compatible

要用图片识别，再加一组视觉上游：

export CG_RAG_VISION_ENDPOINT='https://example.com/v1/chat/completions'
export CG_RAG_VISION_MODEL='your-vlm'
export CG_RAG_VISION_API_KEY='server-side-secret'

检索 profile 的语料、索引、embedding 和 rerank 配置沿用 QUESTION_GENERATED_APP_* 变量及 YAML 映射，完整字段见配置。

2. 启动

cd backend
bash src/run_cg_rag_http.sh

默认地址：

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

首次启动要加载索引，通常需要一分钟左右才会开始应答。

3. 确认服务是否健康

curl --noproxy '*' -sS http://127.0.0.1:8864/cg-rag/health

{
  "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 命令在不同系统上参数不同：

# Linux
IMG=$(base64 -w0 site.jpg)
# macOS
IMG=$(base64 -i site.jpg)

自由生成，一次模型调用、不检索，几秒返回：

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

两者的字段、上限、隐患定级口径和错误码见视觉隐患识别。

下一步