xuelong/Cloud-Tour-to-Libo
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Cloud-Tour-to-Libo/docs/接口文档.md

5.1 KiB
Raw Permalink Blame History

智能客服问答接口使用说明

本文档仅说明第三方系统如何调用百姓惠智能客服问答接口。

1. 接口地址

推荐接口：

POST http://8.163.40.99:8102/v1/openapi/knowledge-qa/query

兼容旧接口：

POST http://8.163.40.99:8102/v1/admin/travel/customer-service-query

2. 请求头

Content-Type: application/json
X-KG-API-Key: <API_KEY>

也兼容：

X-API-Key: <API_KEY>
Authorization: Bearer <API_KEY>

<API_KEY> 由系统管理员提供，不要写在前端代码里。

3. 请求参数

字段 必填 示例 说明
question 是 黄小西三日游多少钱？ 用户自然语言问题
request_id 否 crm-msg-0001 第三方请求 ID
session_id 否 sess-a01 会话 ID
channel 否 crm 来源渠道
customer_id 否 u_10086 第三方客户 ID
graph_name 否 baixinghui_travel_agency 默认可不传

4. 最小请求示例

curl -X POST 'http://8.163.40.99:8102/v1/openapi/knowledge-qa/query' \
  -H 'Content-Type: application/json' \
  -H 'X-KG-API-Key: <API_KEY>' \
  -d '{
    "question": "黄小西三日游多少钱？"
  }'

5. 完整请求示例

curl -X POST 'http://8.163.40.99:8102/v1/openapi/knowledge-qa/query' \
  -H 'Content-Type: application/json' \
  -H 'X-KG-API-Key: <API_KEY>' \
  -d '{
    "request_id": "crm-msg-20260610-0001",
    "session_id": "sess-20260610-a01",
    "channel": "crm",
    "customer_id": "u_10086",
    "graph_name": "baixinghui_travel_agency",
    "question": "轻奢黄小西纯玩3日游多少钱，可以玩几天，期间可以去哪些景区，小七孔附近可以入住什么酒店？"
  }'

6. JavaScript 调用示例

const response = await fetch("http://8.163.40.99:8102/v1/openapi/knowledge-qa/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-KG-API-Key": "<API_KEY>"
  },
  body: JSON.stringify({
    request_id: "crm-msg-20260610-0001",
    session_id: "sess-20260610-a01",
    channel: "crm",
    question: "黄小西三日游多少钱？",
    graph_name: "baixinghui_travel_agency"
  })
});

const data = await response.json();
console.log(data.customer_reply);

7. Python 调用示例

import requests

url = "http://8.163.40.99:8102/v1/openapi/knowledge-qa/query"
headers = {
    "Content-Type": "application/json",
    "X-KG-API-Key": "<API_KEY>",
}
payload = {
    "request_id": "crm-msg-20260610-0001",
    "session_id": "sess-20260610-a01",
    "channel": "crm",
    "question": "黄小西三日游多少钱？",
    "graph_name": "baixinghui_travel_agency",
}

resp = requests.post(url, headers=headers, json=payload, timeout=15)
data = resp.json()
print(data["customer_reply"])

8. 返回示例

{
  "status": "ok",
  "service": "baixinghui_customer_service",
  "request_id": "crm-msg-20260610-0001",
  "trace_id": "trc_xxx",
  "session_id": "sess-20260610-a01",
  "channel": "crm",
  "question": "黄小西三日游多少钱？",
  "graph_name": "baixinghui_travel_agency",
  "answer": "完整回答，适合后台查看。",
  "customer_reply": "客服可直接发送给客户的简短话术。",
  "confidence": 0.88,
  "follow_up_questions": [
    "请提供出发日期和人数。"
  ],
  "risk_notes": [
    "价格、余位、房型和景区政策需按具体团期二次核实。"
  ],
  "knowledge": {
    "plans": [],
    "evidence": []
  },
  "routing": {
    "response_mode": "fast_graph_template",
    "method": "fast_price_quote_graph_template_v1"
  },
  "trace": {
    "latency_ms": 35,
    "stage_timings_ms": {
      "graph_query": 20,
      "answer_synthesis": 0
    }
  }
}

9. 第三方主要读取字段

字段 说明
customer_reply 给客户展示或发送的客服话术
answer 完整答案，适合后台查看
confidence 置信度
follow_up_questions 建议继续追问的问题
risk_notes 需要人工核实的提示
knowledge.evidence 图谱证据
routing.response_mode 当前问答链路
trace_id 排查问题时提供给系统维护人员

10. 常见测试问题

{
  "question": "黄小西三日游多少钱？"
}

{
  "question": "旅行车线路有哪些？"
}

{
  "question": "轻奢黄小西纯玩3日游多少钱，可以玩几天，期间可以去哪些景区，小七孔附近可以入住什么酒店？"
}

{
  "question": "黄小西和小西镇梵哪个更适合老人小孩、不要太累，为什么？"
}

11. 错误码

HTTP 状态 说明
200 请求成功
400 缺少 question 或请求格式错误
401 API Key 缺失或无效
503 服务端未配置 API Key
500/502 服务异常，记录 request_id 联系维护人员

12. 接入建议

  • 第三方系统后端调用接口，不要在前端暴露 API Key。
  • 给客户优先展示 customer_reply。
  • 如果 risk_notes 非空，客服应按提示二次核实。
  • 建议 HTTP 超时设置为 15 秒。