API 说明

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

http://localhost:8102/docs

所有后台接口统一挂载在：

/v1/admin

常用接口

接口	方法	说明
`/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/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 融合成客服可直接使用的话术。没有配置 LLM 时会自动退回图谱模板回答。

认证方式使用接口 Key，默认本地开发值来自 .env / docker-compose.yml 的 INGEST_API_KEYS：

curl http://localhost:8102/v1/admin/travel/customer-service-query \
  -H 'Content-Type: application/json' \
  -H 'X-KG-API-Key: dev-key-1' \
  -d '{
    "question": "黄小西三日游多少钱？",
    "knowledge_graph": "百姓惠",
    "session_id": "demo-session-001",
    "use_llm": true,
    "llm_fusion": true
  }'

常用入参：

字段	说明
`question` / `text`	用户原始咨询内容，必填
`knowledge_graph` / `graph_name`	知识图谱名称，可传 `百姓惠`、`bxh` 或 `baixinghui_travel_agency`
`session_id`	外部客服会话 ID，可选
`customer_context`	外部系统附带的客户上下文，可选
`use_llm`	是否启用 LLM 意图解析，默认 `true`
`llm_fusion`	是否启用 LLM 话术融合，默认 `true`
`return_raw_agent`	是否返回内部图谱问答原始结果，默认 `false`

核心返回字段：

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

前端调用

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

4.8 KiB Raw Blame History Unescape Escape