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

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

## 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` 秒。