API 说明

FastAPI 会自动生成交互式 API 文档。启动服务后访问：

http://localhost:8102/docs

后台管理接口统一挂载在：

/v1/admin

第三方系统对接接口统一挂载在：

/v1/openapi

常用接口

接口	方法	说明
`/v1/admin/health`	`GET`	健康检查
`/v1/admin/auth/login`	`POST`	管理员登录
`/v1/admin/auth/me`	`GET`	当前登录用户
`/v1/admin/projects`	`GET/POST`	项目管理
`/v1/admin/ontology-schemas/current`	`GET`	当前 schema
`/v1/admin/source-profiles`	`GET/POST/PATCH`	数据源管理
`/v1/admin/batches`	`GET`	批次管理
`/v1/admin/entities`	`GET`	候选实体列表
`/v1/admin/conflicts`	`GET`	冲突列表
`/v1/admin/publish-jobs`	`GET/POST`	发布任务
`/v1/admin/graph/overview`	`GET`	图谱概览
`/v1/admin/graph/query`	`POST`	图谱查询
`/v1/admin/plaza/overview`	`GET`	图谱广场概览
`/v1/admin/manual-ingest/extract`	`POST`	手动抽取
`/v1/admin/travel/assistant-query`	`POST`	旅行客服问答
`/v1/openapi/knowledge-qa/query`	`POST`	百姓惠智能客服第三方问答接口
`/v1/admin/travel/customer-service-query`	`POST`	兼容旧版外部问答接口
`/v1/admin/super-agent/run`	`POST`	Super Agent 任务
`/v1/admin/roles`	`GET/POST`	角色管理
`/v1/admin/users`	`GET/POST`	用户管理
`/v1/admin/areas/tree`	`GET`	区域树
`/v1/admin/notifications`	`GET`	通知列表

登录示例

curl -s http://localhost:8102/v1/admin/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin@example.com","password":"change-me"}'

返回中包含 access_token，后续接口可使用：

TOKEN="上一步返回的 access_token"
curl http://localhost:8102/v1/admin/auth/me \
  -H "Authorization: Bearer $TOKEN"

图谱查询示例

curl http://localhost:8102/v1/admin/graph/overview

curl http://localhost:8102/v1/admin/graph/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (n) RETURN n LIMIT 10"}'

旅行客服问答示例

curl http://localhost:8102/v1/admin/travel/assistant-query \
  -H 'Content-Type: application/json' \
  -d '{"question":"黄小西三日游多少钱？"}'

百姓惠智能客服外部接口

该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，按“LLM 生成只读 Cypher -> FalkorDB 图查询 -> LLM 基于证据组织答案”的链路返回客服话术和图谱证据。生产环境需要配置问答环节 LLM。

认证方式使用接口 Key。Key 可以在后台 系统 -> Agent 设置 -> 外部图谱问答 API 维护；同时兼容 .env / docker-compose.yml 的 INGEST_API_KEYS。同一模块底部可以配置“问答环节 LLM 模型”，外部客服话术融合会优先使用该模型，未填写时继承全局 LLM：

curl http://localhost:8102/v1/openapi/knowledge-qa/query \
  -H 'Content-Type: application/json' \
  -H 'X-KG-API-Key: dev-key-1' \
  -d '{
    "request_id": "crm-msg-20260610-0001",
    "question": "黄小西三日游多少钱？",
    "graph_name": "baixinghui_travel_agency",
    "session_id": "demo-session-001",
    "channel": "online_service",
    "customer_id": "customer-001",
    "use_llm": true,
    "llm_fusion": true
  }'

新系统请优先使用 /v1/openapi/knowledge-qa/query；/v1/admin/travel/customer-service-query 仅用于兼容已经接入的内部/旧系统。

常用入参：

字段	说明
`request_id` / `message_id`	外部系统请求或消息 ID，可选；不传时服务端生成
`question` / `text`	用户原始咨询内容，必填
`graph_name` / `knowledge_graph`	知识图谱名称；不传时使用后台默认图谱。百姓惠可传 `百姓惠`、`bxh` 或 `baixinghui_travel_agency`
`session_id`	外部客服会话 ID，可选
`channel`	来源渠道，如 `web`、`wechat`、`online_service`，可选
`customer_id` / `external_user_id`	外部客户 ID，可选
`customer_context`	外部系统附带的客户上下文，可选
`use_llm`	是否启用 LLM 意图解析，默认 `true`
`llm_fusion`	是否启用 LLM 话术融合，默认 `true`
`return_raw_agent`	是否返回内部图谱问答原始结果，默认 `false`

核心返回字段：

字段	说明
`request_id`	外部请求 ID，原样回传或由服务端生成
`trace_id`	服务端链路追踪 ID，排查问题时使用
`answer`	给外部系统展示的完整回答
`customer_reply`	可直接发给客户的话术
`confidence`	本次回答置信度
`follow_up_questions`	建议追问
`risk_notes`	不可直接承诺或需二次核实的事项
`knowledge.plans`	图谱命中的线路/方案
`knowledge.evidence`	图谱证据
`routing.intent`	解析出的客户需求
`trace`	响应耗时、召回规模、质量检查摘要

认证请求头支持三种写法，推荐第一种：

X-KG-API-Key: <api-key>
X-API-Key: <api-key>
Authorization: Bearer <api-key>

生产环境必须至少配置一个 API Key；未配置时，对外问答接口会返回 503，表示接口尚未启用。不要使用 dev-key-1 这类弱密钥作为生产 Key；建议使用高强度随机字符串，按周期轮换，并优先通过环境变量 INGEST_API_KEYS 或后台配置统一管理。

常见错误码：

状态码	说明
`400`	请求体缺少 `question`
`401`	API Key 缺失或无效
`502`	图查询、LLM 生成 Cypher 或答案合成失败
`503`	后台未配置接口 API Key

前端调用

React 管理后台通过 admin-web/src/api.ts 访问同源 API。Docker 部署时前端和 API 同在 http://localhost:8102，因此无需额外配置跨域代理。

本地问答效果可在 http://localhost:8102/admin/plaza/user 验证。当前项目图谱选择 baixinghui_travel_agency 时，该页面会走百姓惠旅行社客服问答；选择城市空间图谱时仍为附近地点问答。

外部服务

LLM 和高德地图相关能力默认关闭或留空。启用前需要在 .env 或 Docker Compose 环境变量中配置：

LLM_API_BASE
LLM_API_KEY
LLM_MODEL
LLM_EXTRACTION_ENABLED=true
AMAP_WEB_KEY
AMAP_JS_KEY
AMAP_SECURITY_JSCODE
GAODE_CRAWLER_PATH

6.5 KiB Raw Permalink Blame History Unescape Escape