Add Cloud Tour Libo knowledge graph platform
This commit is contained in:
212
docs/接口文档.md
Normal file
212
docs/接口文档.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 智能客服问答接口使用说明
|
||||
|
||||
本文档仅说明第三方系统如何调用百姓惠智能客服问答接口。
|
||||
|
||||
## 1. 接口地址
|
||||
|
||||
推荐接口：
|
||||
|
||||
```text
|
||||
POST http://8.163.40.99:8102/v1/openapi/knowledge-qa/query
|
||||
```
|
||||
|
||||
兼容旧接口：
|
||||
|
||||
```text
|
||||
POST http://8.163.40.99:8102/v1/admin/travel/customer-service-query
|
||||
```
|
||||
|
||||
|
||||
## 2. 请求头
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
X-KG-API-Key: <API_KEY>
|
||||
```
|
||||
|
||||
也兼容：
|
||||
|
||||
```http
|
||||
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. 最小请求示例
|
||||
|
||||
```bash
|
||||
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. 完整请求示例
|
||||
|
||||
```bash
|
||||
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 调用示例
|
||||
|
||||
```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 调用示例
|
||||
|
||||
```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. 返回示例
|
||||
|
||||
```json
|
||||
{
|
||||
"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. 常见测试问题
|
||||
|
||||
```json
|
||||
{
|
||||
"question": "黄小西三日游多少钱？"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"question": "旅行车线路有哪些？"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"question": "轻奢黄小西纯玩3日游多少钱，可以玩几天，期间可以去哪些景区，小七孔附近可以入住什么酒店？"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"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` 秒。
|
||||
Reference in New Issue
Block a user