7.2 KiB

Raw Blame History

LawRisk 检索接口文档

Base URL: https://YOUR_HOST
路径: /fs-ai-asistant/api/workflow/lawrisk
方法: POST（推荐）, GET（便捷调试）
鉴权: 无（如需可在网关/反向代理层添加）
CORS: 已启用（复用 smart_cors_middleware.py）

请求格式

Content-Type: application/x-www-form-urlencoded
表单字段
- query | q | text (string，必填): 用户输入的中文问题
- mode (string，可选): llm(默认) 或 embed
- debug (boolean-like，可选): 1/true/yes/on 视为开启调试
- top (int，可选): 调试时返回候选数量（默认 5）

提示: GET 模式下同名参数通过查询串传递；POST 模式优先解析 x-www-form-urlencoded，若未提供则回退 JSON(application/json)。

响应

成功 (200)
- risk_subject: 数组，每项包含
  - id (string)
  - name (string)
  - permit_ids (string[])
  - score (number，可选，仅在 debug=1 且 embed 模式或回退时出现)
- debug (object，可选，debug=1 时返回)
  - model (string): 使用模型（如 qwen-plus-latest）
  - num_subjects (number): 参与检索的主题数量
  - selected_ids (string[], 仅 llm 模式): LLM 选择的主题 ID 列表
  - thresholds (object, 仅 embed 模式): 相似度阈值
  - top_candidates (array, 仅 embed 模式): 前 N 候选及分数
  - allow_empty (boolean): LLM 允许返回空结果
失败
- 400: { "error": "query is required" }
- 500: { "error": "<错误信息>" }

示例

POST（推荐，LLM 模式 + 调试）

curl -s -X POST "http://www.chinaweal.com.cn:8090/fs-ai-asistant/api/workflow/lawrisk" -H "Content-Type: application/x-www-form-urlencoded" -d "query=我要办一家电影院&mode=llm&debug=1&top=5"

示例响应（命中）

{ "risk_subject": [ {"id":"384a...05e7","name":"开办电影院","permit_ids":["04bf...","509b...","..."]} ], "debug": { "model": "qwen-plus-latest", "num_subjects": 123, "selected_ids": ["384a...05e7"], "allow_empty": true } }

示例响应（无匹配，允许空）

{ "risk_subject": [], "debug": { "model": "qwen-plus-latest", "num_subjects": 123, "selected_ids": [], "allow_empty": true } }

GET 便捷调试

curl -s "http://www.chinaweal.com.cn:8090T/fs-ai-asistant/api/workflow/lawrisk?query=%E6%88%91%E8%A6%81%E5%8A%9E%E4%B8%80%E5%AE%B6%E7%94%B5%E5%BD%B1%E9%99%A2&mode=llm&debug=1&top=5"

前端调用示例（fetch）

fetch("http://www.chinaweal.com.cn:8090/fs-ai-asistant/api/workflow/lawrisk", { method: "POST", headers: {"Content-Type": "application/x-www-form-urlencoded"}, body: new URLSearchParams({ query: "我要办一家电影院", mode: "llm", debug: "1", top: "5" }) }).then(r => r.json()).then(console.log)

模式说明

llm（默认）：将主题清单（id 与名称）传给 Qwen（qwen-plus-latest），由 LLM 选择最相关的一个或多个主题 ID；若判断无匹配，返回空数组。
embed（可选）：基于向量相似度检索；阈值可通过环境变量配置（LAWRISK_RETURN_IF_GE、LAWRISK_FALLBACK_GT）。

LawRisk V2 接口（结构化结果）

Base URL: https://YOUR_HOST
路径: /fs-ai-asistant/api/workflow/lawrisk/v2
方法: POST（推荐）, GET（调试）
Content-Type: application/x-www-form-urlencoded 或 application/json
鉴权: 无

请求参数

query | q | text (string，必填): 用户问题。
debug (boolean-like，可选): 1/true/yes/on 视为开启调试信息。
top (int，可选): 用于推荐问题数量，默认 5。
region | region_id (string/list，可选): 限定地区，可传地区 ID、名称或 地区 · 主题 展示名，多值可用 region=市级&region=禅城区。

响应结构

成功响应示例（结构化结果，含调试开关）：

{
  "success": true,
  "message": "OK",
  "data": {
    "workflowStatus": "ok",
    "executionTime": 412,
    "questionExtend": ["电影院需要哪些许可？", "电影放映许可证办理条件？"],
    "risk_subject": [
      {
        "id": "2:18",
        "display_name": "市级 · 开办电影院",
        "region": {"id": "2", "name": "市级"},
        "theme": {"id": "18", "name": "开办电影院"},
        "permits": [
          {
            "id": "509",
            "name": "电影放映单位设立审批",
            "permit_status": "许可",
            "subitem_summary": "设立固定电影院",
            "responsible_contact": "市文化广电旅游局",
            "jurisdiction_scope": "佛山市行政区域",
            "business_scopes": [{"id": "901", "description": "电影放映"}],
            "risks": [
              {
                "id": "1205",
                "risk_content": "未取得审批擅自放映电影属于违法行为。",
                "legal_basis": "《电影产业促进法》第四十四条",
                "document_no": "",
                "summary": "**第四十四条** …"
              }
            ]
          }
        ]
      }
    ],
    "debug": {
      "catalog_total": 123,
      "catalog_used_for_llm": 78,
      "selected_option_ids": ["2:18"]
    }
  }
}

字段说明：

success/message/data：与 V1 保持一致。
data.risk_subject: 数组。每项包含所选地区、主题及关联许可。
- id/display_name: LLM 选择的 地区ID:主题ID 和展示名。若直接命中许可名称，为空字符串。
- region/theme: 结构体，含 id/name。
- permits: 许可列表，含 business_scopes（经营范围数组），risks（风险提示数组），以及可选的 permit_status、subitem_summary、responsible_contact、jurisdiction_scope。
data.debug: 仅在 debug=1 时返回，包含 catalog 规模、选中项、命中策略（直接命中许可时为 strategy: permit_exact 等）。

失败响应：

400: { "error": "query is required" }
500: { "success": false, "message": "<错误信息>", "data": {} }

便捷请求示例

POST（推荐）：

curl -s -X POST "https://YOUR_HOST/fs-ai-asistant/api/workflow/lawrisk/v2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=我要开电影院&debug=1&region=市级"

GET 调试：

curl -s "https://YOUR_HOST/fs-ai-asistant/api/workflow/lawrisk/v2?query=%E6%88%91%E8%A6%81%E5%BC%80%E7%94%B5%E5%BD%B1%E9%99%A2&debug=1"

前端 fetch 示例：

const params = new URLSearchParams({ query: "我要开电影院", debug: "1" });
fetch("/fs-ai-asistant/api/workflow/lawrisk/v2", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: params.toString(),
})
  .then((res) => res.json())
  .then(({ data }) => {
    // data.risk_subject[0].permits[0].risks ...
  });

地区列表接口

路径: /fs-ai-asistant/api/workflow/lawrisk/v2/regions
方法: GET
响应:

{
  "success": true,
  "data": {
    "regions": [
      {"id": "2", "name": "市级"},
      {"id": "5", "name": "禅城区"}
    ]
  }
}

该接口返回所有可用地区，以便前端构建地区筛选下拉框。调用搜索接口时，可将 region 参数设置为选中的 id 或 name。

兼容与跨域

服务端已启用 CORS，可在 .env 中配置：ALLOWED_ORIGINS、CORS_STRICT、CORS_DEBUG、NGINX_CORS_MODE 等。
如需鉴权（例如加 Token），建议在网关或反代层统一处理。

7.2 KiB Raw Blame History Unescape Escape