Add customer service API deployment support
This commit is contained in:
@@ -31,6 +31,7 @@ http://localhost:8102/docs
|
||||
| `/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` | 用户管理 |
|
||||
@@ -73,10 +74,57 @@ curl http://localhost:8102/v1/admin/travel/assistant-query \
|
||||
-d '{"question":"黄小西三日游多少钱？"}'
|
||||
```
|
||||
|
||||
## 百姓惠智能客服外部接口
|
||||
|
||||
该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，先召回图谱线路、报价口径、费用、酒店、餐饮、车辆和证据，再用 LLM 融合成客服可直接使用的话术。没有配置 LLM 时会自动退回图谱模板回答。
|
||||
|
||||
认证方式使用接口 Key，默认本地开发值来自 `.env` / `docker-compose.yml` 的 `INGEST_API_KEYS`：
|
||||
|
||||
```bash
|
||||
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 环境变量中配置：
|
||||
|
||||
@@ -21,6 +21,14 @@ docker compose up -d --build
|
||||
http://localhost:8102/admin
|
||||
```
|
||||
|
||||
服务器部署后把 `localhost` 换成服务器 IP 或域名。例如本项目迁移到 `8.163.40.99` 后：
|
||||
|
||||
```text
|
||||
http://8.163.40.99:8102/admin
|
||||
http://8.163.40.99:8102/docs
|
||||
http://8.163.40.99:8102/openapi.json
|
||||
```
|
||||
|
||||
默认账号：
|
||||
|
||||
```text
|
||||
@@ -62,6 +70,39 @@ docker compose down -v
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
## 无 sudo 服务器的 rootless Docker 启动
|
||||
|
||||
如果服务器账号不能使用 `sudo`，并且 `loginctl show-user <用户> -p Linger` 显示 `Linger=no`，用户级 `docker.service` 可能会在 SSH 退出后停止。此时可以使用项目脚本把 rootless Docker 的 socket 固定到用户目录：
|
||||
|
||||
```bash
|
||||
cd /home/dockerop/travel-knowledge-graph
|
||||
./scripts/server_rootless_docker.sh start
|
||||
./scripts/server_rootless_docker.sh up
|
||||
./scripts/server_rootless_docker.sh ps
|
||||
./scripts/server_rootless_docker.sh health
|
||||
```
|
||||
|
||||
本项目在 `8.163.40.99` 的当前部署使用：
|
||||
|
||||
```bash
|
||||
DOCKER_HOST=unix:///home/dockerop/.docker/run/docker.sock
|
||||
```
|
||||
|
||||
如果服务器重启，重新执行：
|
||||
|
||||
```bash
|
||||
cd /home/dockerop/travel-knowledge-graph
|
||||
./scripts/server_rootless_docker.sh up
|
||||
```
|
||||
|
||||
更推荐的长期方式是让服务器管理员执行：
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger dockerop
|
||||
```
|
||||
|
||||
这样 rootless Docker 可以由 systemd 用户服务长期托管。
|
||||
|
||||
## 端口配置
|
||||
|
||||
可以在启动时覆盖端口：
|
||||
@@ -87,8 +128,25 @@ docker compose up -d --build
|
||||
|
||||
Docker Compose 已提供可运行默认值。生产部署时建议改成 `.env` 文件或部署平台的环境变量。
|
||||
|
||||
服务器首次部署建议复制模板后修改：
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
至少修改：
|
||||
|
||||
```env
|
||||
AUTH_SECRET=换成32位以上随机字符串
|
||||
AUTH_DEFAULT_PASSWORD=换成后台管理员密码
|
||||
INGEST_API_KEYS=换成给外部系统的接口Key
|
||||
LLM_API_BASE=你的OpenAI兼容模型地址
|
||||
LLM_API_KEY=你的模型Key
|
||||
```
|
||||
|
||||
| 变量 | 说明 |
|
||||
| --- | --- |
|
||||
| `POSTGRES_USER`、`POSTGRES_PASSWORD`、`POSTGRES_DB` | PostgreSQL 容器账号、密码、库名 |
|
||||
| `DATABASE_URL` | 后端连接 PostgreSQL 的 URL |
|
||||
| `DB_SCHEMA` | 默认 `kg_admin_new2` |
|
||||
| `DB_MIGRATIONS_ENABLED` | 快照部署默认 `false` |
|
||||
@@ -106,6 +164,44 @@ Docker Compose 已提供可运行默认值。生产部署时建议改成 `.env`
|
||||
| `TRAVEL_DELIVERY_ROOT` | POI 交付 CSV 目录，仅运行采集/增强脚本时需要 |
|
||||
| `TRAVEL_KG_EXPORT_ROOT` | 采集/构图脚本导出目录 |
|
||||
|
||||
## 百姓惠智能客服接口
|
||||
|
||||
给外部系统对接时，只开放这个接口即可：
|
||||
|
||||
```text
|
||||
POST http://8.163.40.99:8102/v1/admin/travel/customer-service-query
|
||||
```
|
||||
|
||||
服务器安全组需要放行 TCP `8102`。如果服务器本机 `curl http://127.0.0.1:8102/v1/admin/health` 正常，但外部访问 `http://8.163.40.99:8102` 超时，优先检查云控制台安全组/防火墙入方向规则。
|
||||
|
||||
请求示例：
|
||||
|
||||
```bash
|
||||
curl http://8.163.40.99:8102/v1/admin/travel/customer-service-query \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'X-KG-API-Key: 你的INGEST_API_KEYS之一' \
|
||||
-d '{
|
||||
"question": "黄小西三日游多少钱？",
|
||||
"knowledge_graph": "百姓惠",
|
||||
"session_id": "demo-001",
|
||||
"use_llm": true,
|
||||
"llm_fusion": true
|
||||
}'
|
||||
```
|
||||
|
||||
`llm_fusion=true` 需要配置 `LLM_API_BASE` 和 `LLM_API_KEY`。未配置 key 时，接口仍会返回图谱模板答案，但不会调用 LLM 融合。
|
||||
|
||||
主要返回字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `answer` | 给外部系统展示的完整回答 |
|
||||
| `customer_reply` | 可以直接发给客户的话术 |
|
||||
| `follow_up_questions` | 建议追问 |
|
||||
| `risk_notes` | 需要二次核实或不可直接承诺的事项 |
|
||||
| `knowledge.plans` | 图谱命中的线路/方案 |
|
||||
| `knowledge.evidence` | 图谱证据 |
|
||||
|
||||
## 健康检查
|
||||
|
||||
API：
|
||||
|
||||
Reference in New Issue
Block a user