HTTP API

本文描述 CG_RAG 当前对外暴露的 HTTP API。示例默认服务地址为：

http://127.0.0.1:8864

如通过代理或网关访问，请把示例中的主机和端口替换为实际入口。

核心约定

• CG_RAG 编排不包含 domain gate。
• retrieve-rerank 只返回候选文档，不调用 LLM。
• constrained-generate 只基于调用方传入的候选文档做受约束生成。
• rag 和 answer 会串联 retrieve、rerank、constrained generation；answer 是当前 HTTP 兼容别名。
• 可用 scope 为 full、usual、usual_plus_law。自动化调用建议显式传入目标 scope。
• topk 会被限制在 1..200，max_items 会被限制在 1..20。
• include_debug 必须是 JSON boolean；"true"、1、0 等字符串或数字会被判为无效请求。
• constrained generation 默认返回 compact 输出；只有 include_debug: true 时才返回调试字段。
• retrieve-rerank 缓存只覆盖检索和重排结果，不缓存 LLM generation。
• retriever manager 同时只保留一个 active profile。warmup 会顺序加载 scopes，但最终只保留最后一个 active scope。

接口总览

方法	路径	用途	业务状态字段
GET	/cg-rag/health	服务健康、profile、rerank 和 LLM 配置摘要	ok
GET	/cg-rag/profiles	列出可用检索范围	裸 profile map
POST	/cg-rag/retrieve-rerank	只执行 retrieve + rerank	num_docs、cache.hit
POST	/cg-rag/constrained-generate	对调用方传入的候选文档做受约束生成	ok
POST	/cg-rag/rag	完整 retrieve + rerank + constrained generation	generation.ok
POST	/cg-rag/answer	/cg-rag/rag 的兼容别名	generation.ok
POST	/cg-rag/warmup	加载一个或多个检索 scope	ok、final_active_scope

HTTP 响应会带 X-Request-ID header。调用方传入合法 X-Request-ID 时服务会回传该值；未传入时服务会生成 req_*。多数 JSON body 也会包含 request_id，但 /cg-rag/profiles 成功响应保持裸 profile map。

GET /cg-rag/health

请求：

curl --noproxy '*' -sS \
  -H 'X-Request-ID: req-doc-health' \
  http://127.0.0.1:8864/cg-rag/health

示例输出，已删减：

{
  "ok": true,
  "request_id": "req-doc-health",
  "service": "CG_RAG",
  "http_prefix": "/cg-rag",
  "mcp_path": "/cg-rag/mcp",
  "available_scopes": ["full", "usual", "usual_plus_law"],
  "default_scope": "full",
  "active_scope": "full",
  "config_issues": [],
  "generation": {
    "configured": true,
    "endpoint_configured": true,
    "endpoint_host": "<GENERATION_ENDPOINT_HOST>",
    "model": "deepseek-chat",
    "response_format_json": true,
    "enable_thinking": false,
    "timeout_seconds": 120.0,
    "max_context_docs": 78,
    "default_max_items": 10
  },
  "rerank": {
    "api_enabled": false,
    "model": "qwen-rerank"
  }
}

config_issues 非空时表示服务可启动，但部分能力可能不可用。例如 generation endpoint 或 model 未配置时，retrieve-rerank 仍可用，constrained generation 会返回业务错误。

GET /cg-rag/profiles

请求：

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

示例输出，已删减：

{
  "full": {
    "label": "全库",
    "retrieval_method": "qwen3-0.6b"
  },
  "usual": {
    "label": "常用规范",
    "retrieval_method": "qwen3-0.6b"
  },
  "usual_plus_law": {
    "label": "常用规范+常用法律",
    "retrieval_method": "qwen3-0.6b"
  }
}

POST /cg-rag/retrieve-rerank

请求字段：

字段	类型	必填	默认	说明
query	string	是	无	用户问题；会去除首尾空白，不能为空
scope	string	否	usual	检索范围；建议显式传入
topk	integer	否	78	返回候选数，范围 1..200

请求：

curl --noproxy '*' -sS \
  -X POST http://127.0.0.1:8864/cg-rag/retrieve-rerank \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: req-doc-retrieve' \
  -d '{"query":"脚手架验收需要检查哪些条文？","scope":"full","topk":2}'

示例输出，已删减：

{
  "query": "脚手架验收需要检查哪些条文？",
  "request_id": "req-doc-retrieve",
  "num_docs": 2,
  "topk": 2,
  "cache": {
    "hit": false
  },
  "pipeline": {
    "requested_scope": "full",
    "active_scope": "full",
    "scope_switched": false,
    "rerank_enabled": true,
    "api_rerank_enabled": false,
    "rerank_backend": "transformers",
    "retrieval_time_ms": 126.4,
    "rerank_time_ms": 44.8,
    "search_total_time_ms": 178.2
  },
  "retrieval_docs": [
    {
      "law_name": "JGJ166-2016建筑施工碗扣式钢管脚手架安全技术规范",
      "article_number": "9.0.8(4)",
      "contents": "脚手架验收合格投入使用后，在使用过程中应定期检查，检查项目应符合下列规定：4 架体应无超载使用情况。"
    },
    {
      "law_name": "GB55023-2022施工脚手架通用规范",
      "article_number": "6.0.5(1)",
      "contents": "脚手架搭设达到设计高度或安装就位后，应进行验收，验收不合格的，不得使用。"
    }
  ]
}

缓存命中时 cache.hit 为 true。缓存 key 包含 normalized scope、去首尾空白后的 query 和 topk。

POST /cg-rag/constrained-generate

请求字段：

字段	类型	必填	默认	说明
query	string	是	无	用户问题
retrieval_docs	array	是	无	候选文档，通常来自 /cg-rag/retrieve-rerank
max_items	integer	否	10	最多返回条文数，范围 1..20
include_debug	boolean	否	false	是否返回调试字段

请求：

curl --noproxy '*' -sS \
  -X POST http://127.0.0.1:8864/cg-rag/constrained-generate \
  -H 'Content-Type: application/json' \
  -d '{
    "query":"脚手架验收需要检查哪些条文？",
    "max_items":2,
    "include_debug":false,
    "retrieval_docs":[
      {
        "law_name":"GB55023-2022施工脚手架通用规范",
        "article_number":"6.0.5(1)",
        "contents":"脚手架搭设达到设计高度或安装就位后，应进行验收，验收不合格的，不得使用。"
      }
    ]
  }'

示例输出，已删减：

{
  "ok": true,
  "generation_mode": "constrained",
  "answer_text": "GB55023-2022施工脚手架通用规范 6.0.5(1)",
  "pred_indices": [1],
  "pred_items": [
    "GB55023-2022施工脚手架通用规范 6.0.5(1)"
  ],
  "pred_raw": "{\"indices\":[1]}",
  "thinking": "",
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 8,
    "total_tokens": 1208
  }
}

POST /cg-rag/rag

请求字段：

字段	类型	必填	默认	说明
query	string	是	无	用户问题
scope	string	否	usual	检索范围；建议显式传入
topk	integer	否	78	检索候选数，范围 1..200
max_items	integer	否	10	最多返回条文数，范围 1..20
include_debug	boolean	否	false	是否在 generation 中返回调试字段

请求：

curl --noproxy '*' -sS \
  -X POST http://127.0.0.1:8864/cg-rag/rag \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: req-doc-rag' \
  -d '{"query":"脚手架验收需要检查哪些条文？","scope":"full","topk":20,"max_items":5}'

示例输出，已删减：

{
  "query": "脚手架验收需要检查哪些条文？",
  "request_id": "req-doc-rag",
  "retrieval": {
    "query": "脚手架验收需要检查哪些条文？",
    "num_docs": 20,
    "topk": 20,
    "cache": {
      "hit": false
    },
    "pipeline": {
      "active_scope": "full",
      "rerank_enabled": true
    },
    "retrieval_docs": [
      {
        "law_name": "GB55023-2022施工脚手架通用规范",
        "article_number": "6.0.5(1)",
        "contents": "脚手架搭设达到设计高度或安装就位后，应进行验收，验收不合格的，不得使用。"
      }
    ]
  },
  "generation": {
    "ok": true,
    "generation_mode": "constrained",
    "answer_text": "GB55023-2022施工脚手架通用规范 6.0.5(1)",
    "pred_indices": [1],
    "pred_items": [
      "GB55023-2022施工脚手架通用规范 6.0.5(1)"
    ],
    "pred_raw": "{\"indices\":[1]}",
    "thinking": "",
    "usage": {
      "total_tokens": 1208
    }
  }
}

POST /cg-rag/answer

/cg-rag/answer 当前等价于 /cg-rag/rag，请求字段和响应结构一致。新集成建议优先使用 /cg-rag/rag，需要保留 answer 命名时再使用该别名。

POST /cg-rag/warmup

请求字段：

字段	类型	必填	默认	说明
scopes	array of string	否	所有可用 scopes	要顺序加载的 scope 列表

请求：

curl --noproxy '*' -sS \
  -X POST http://127.0.0.1:8864/cg-rag/warmup \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: req-doc-warmup' \
  -d '{"scopes":["full"]}'

示例输出：

{
  "ok": true,
  "request_id": "req-doc-warmup",
  "requested_scopes": ["full"],
  "warmed_scopes": ["full"],
  "final_active_scope": "full",
  "warmed": [
    {
      "requested_scope": "full",
      "normalized_scope": "full",
      "active_scope": "full",
      "warmed": true,
      "resident": true,
      "scope_switched": false
    }
  ]
}

warmup 是顺序加载，不是多 profile 常驻。传入多个 scope 时，只有最后一个 scope 会成为最终 resident scope。

错误和业务失败

HTTP 请求体验证失败返回 HTTP 400：

{
  "request_id": "req_xxx",
  "error": {
    "code": "invalid_request",
    "message": "请求参数无效，请检查字段类型、范围和必填项。",
    "details": {
      "errors": [
        {
          "loc": ["include_debug"],
          "message": "Input should be a valid boolean",
          "type": "bool_type"
        }
      ]
    }
  }
}

非预期服务异常返回 HTTP 500：

{
  "request_id": "req_xxx",
  "error": {
    "code": "service_error",
    "message": "CG_RAG 服务调用失败，请稍后重试或检查服务日志。",
    "details": {}
  }
}

生成接口未配置属于业务失败，不是 HTTP 500。/cg-rag/constrained-generate 示例：

{
  "ok": false,
  "error": {
    "code": "generation_not_configured",
    "message": "CG_RAG 生成接口未配置，请设置 CG_RAG_GENERATION_ENDPOINT 和 CG_RAG_GENERATION_MODEL。",
    "details": {}
  },
  "pred_indices": [],
  "pred_items": [],
  "pred_raw": ""
}

完整 RAG 没有稳定候选时，/cg-rag/rag 和 /cg-rag/answer 不会把空候选传给 constrained generation，也不会返回 HTTP 500；它们会返回 generation.ok: false：

{
  "query": "一个没有稳定命中的问题",
  "retrieval": {
    "num_docs": 0,
    "retrieval_docs": []
  },
  "generation": {
    "ok": false,
    "error": {
      "code": "no_stable_article",
      "message": "当前在线候选中未稳定选出明确条文。",
      "details": {}
    },
    "pred_indices": [],
    "pred_items": [],
    "pred_raw": ""
  }
}

集成建议

• 调用 retrieve-only 场景时优先使用 /cg-rag/retrieve-rerank，不要调用完整 RAG 后丢弃 generation。
• 调用完整 RAG 时优先检查 generation.ok，不要只看 HTTP 状态码。
• 生产调用建议显式传 scope、topk 和 max_items，避免默认值变化影响结果。
• 调试时短期开启 include_debug: true；常规服务调用保持默认 false，减少响应体和敏感配置暴露。