fs-lawrisk/API.md

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）。

兼容与跨域

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