213 lines
5.1 KiB
Markdown
213 lines
5.1 KiB
Markdown
# 智能客服问答接口使用说明
|
||
|
||
本文档仅说明第三方系统如何调用百姓惠智能客服问答接口。
|
||
|
||
## 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` 秒。
|