QA反馈模块API调用说明

📋 概述

QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答结果进行点赞/点踩反馈，并将反馈数据转化为训练数据。本模块包含6个主要API端点，支持反馈记录的创建、查询、修改、删除以及训练数据集成。

🔧 基础信息

基础URL: http://localhost:8084
API前缀: /api/v0/qa_feedback/
数据格式: JSON
字符编码: UTF-8

🔍 API端点一览

API端点	方法	功能描述
`/api/v0/qa_feedback/query`	POST	查询反馈记录（支持分页、筛选、排序）
`/api/v0/qa_feedback/delete/{feedback_id}`	DELETE	删除指定反馈记录
`/api/v0/qa_feedback/update/{feedback_id}`	PUT	修改指定反馈记录
`/api/v0/qa_feedback/add_to_training`	POST	核心功能：批量添加到训练集
`/api/v0/qa_feedback/add`	POST	创建新的反馈记录
`/api/v0/qa_feedback/stats`	GET	获取反馈统计信息

📖 详细API说明

1. 查询反馈记录 API

端点: POST /api/v0/qa_feedback/query

功能: 查询反馈记录，支持分页、筛选和排序功能，主要用于审核页面展示反馈数据。

📝 请求参数

参数名	类型	必填	默认值	说明
`page`	int	否	1	页码（从1开始）
`page_size`	int	否	20	每页记录数（范围：1-100）
`is_thumb_up`	boolean	否	null	筛选点赞状态（true=点赞，false=点踩）
`create_time_start`	string	否	null	创建时间开始（格式：YYYY-MM-DD）
`create_time_end`	string	否	null	创建时间结束（格式：YYYY-MM-DD）
`is_in_training_data`	boolean	否	null	是否已加入训练数据
`sort_by`	string	否	"create_time"	排序字段（id/create_time/update_time/user_id）
`sort_order`	string	否	"desc"	排序方向（asc/desc）

🌰 请求示例

基础查询：

{
  "page": 1,
  "page_size": 10
}

完整筛选查询：

{
  "page": 1,
  "page_size": 20,
  "is_thumb_up": true,
  "create_time_start": "2024-01-01",
  "create_time_end": "2024-12-31",
  "is_in_training_data": false,
  "sort_by": "create_time",
  "sort_order": "desc"
}

查询未训练的负向反馈：

{
  "is_thumb_up": false,
  "is_in_training_data": false,
  "sort_by": "create_time",
  "sort_order": "asc"
}

✅ 成功响应格式

{
    "code": 200,
    "data": {
        "pagination": {
            "has_next": false,
            "has_prev": false,
            "page": 1,
            "page_size": 5,
            "total": 4,
            "total_pages": 1
        },
        "records": [
            {
                "create_time": "2024-01-18T11:40:00",
                "id": 8,
                "is_in_training_data": false,
                "is_thumb_up": true,
                "question": "按月统计订单趋势",
                "sql": "SELECT DATE_TRUNC('month', create_time) as month, COUNT(*) as order_count FROM orders GROUP BY month ORDER BY month;",
                "update_time": null,
                "user_id": "user007"
            },
            {
                "create_time": "2024-01-17T13:25:00",
                "id": 7,
                "is_in_training_data": false,
                "is_thumb_up": true,
                "question": "查询用户余额",
                "sql": "SELECT user_id, account_balance FROM user_accounts WHERE user_id = '12345';",
                "update_time": null,
                "user_id": "user006"
            },
            {
                "create_time": "2024-01-16T16:30:00",
                "id": 5,
                "is_in_training_data": false,
                "is_thumb_up": true,
                "question": "查询今日新增用户",
                "sql": "SELECT COUNT(*) as new_users FROM users WHERE DATE(create_time) = CURRENT_DATE;",
                "update_time": null,
                "user_id": "user005"
            },
            {
                "create_time": "2024-01-16T09:45:00",
                "id": 4,
                "is_in_training_data": false,
                "is_thumb_up": true,
                "question": "按服务区统计营收",
                "sql": "SELECT service_name, SUM(pay_sum) as total_revenue FROM bss_business_day_data WHERE delete_ts IS NULL GROUP BY service_name ORDER BY total_revenue DESC;",
                "update_time": null,
                "user_id": "user004"
            }
        ],
        "response": "查询成功，共找到 4 条记录"
    },
    "message": "操作成功",
    "success": true
}

2. 删除反馈记录 API

端点: DELETE /api/v0/qa_feedback/delete/{feedback_id}

功能: 根据记录ID删除指定的反馈记录。

📝 路径参数

参数名	类型	必填	说明
`feedback_id`	int	是	反馈记录的ID

🌰 请求示例

DELETE /api/v0/qa_feedback/delete/123

✅ 成功响应格式

{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {
    "response": "反馈记录删除成功",
    "deleted_id": 123
  }
}

❌ 失败响应格式

{
  "code": 404,
  "success": false,
  "message": "资源未找到",
  "data": {
    "response": "反馈记录不存在 (ID: 123)",
    "timestamp": "2024-06-24T10:30:00"
  }
}

3. 修改反馈记录 API

端点: PUT /api/v0/qa_feedback/update/{feedback_id}

功能: 修改指定反馈记录的内容。

📝 路径参数

参数名	类型	必填	说明
`feedback_id`	int	是	反馈记录的ID

📝 请求参数

参数名	类型	必填	说明
`question`	string	否	问题内容
`sql`	string	否	SQL内容
`is_thumb_up`	boolean	否	是否点赞
`user_id`	string	否	用户ID
`is_in_training_data`	boolean	否	是否已加入训练数据

🌰 请求示例

修改问题和SQL：

{
  "question": "查询活跃用户信息",
  "sql": "SELECT * FROM users WHERE status = 'active'"
}

修改反馈状态：

{
  "is_thumb_up": false,
  "is_in_training_data": true
}

✅ 成功响应格式

{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {
    "response": "反馈记录更新成功",
    "updated_id": 123,
    "updated_fields": ["question", "sql"]
  }
}

4. 添加到训练数据集 API ⭐

端点: POST /api/v0/qa_feedback/add_to_training

功能: 核心功能，将反馈记录批量添加到训练数据集。支持混合处理：正向反馈（点赞）加入SQL训练集，负向反馈（点踩）加入错误SQL训练集。

📝 请求参数

参数名	类型	必填	说明
`feedback_ids`	array[int]	是	反馈记录ID列表

🌰 请求示例

批量添加训练数据：

{
  "feedback_ids": [17]
}

✅ 成功响应格式

{
    "code": 200,
    "data": {
        "response": "训练数据添加完成，成功处理 1 条记录",
        "successfully_trained_ids": [
            17
        ],
        "summary": {
            "already_trained": 0,
            "errors": 0,
            "negative_trained": 1,
            "positive_trained": 0,
            "total_processed": 1,
            "total_requested": 1
        },
        "training_details": {
            "error_sql_training_count": 1,
            "sql_training_count": 0
        }
    },
    "message": "操作成功",
    "success": true
}

🔄 处理逻辑说明

正向反馈 (is_thumb_up=true) → 调用 vn.train(question, sql)
负向反馈 (is_thumb_up=false) → 调用 vn.train_error_sql(question, sql)
已训练记录 → 跳过处理
训练成功 → 自动标记 is_in_training_data=true

5. 创建反馈记录 API

端点: POST /api/v0/qa_feedback/add

功能: 创建新的反馈记录，通常由前端在用户点赞/点踩时调用。

📝 请求参数

参数名	类型	必填	默认值	说明
`question`	string	是	-	用户问题
`sql`	string	是	-	生成的SQL
`is_thumb_up`	boolean	是	-	是否点赞
`user_id`	string	否	"guest"	用户ID

🌰 请求示例

用户点赞示例：

{
  "question": "查询所有部门信息",
  "sql": "SELECT * FROM departments",
  "is_thumb_up": true,
  "user_id": "user123"
}

用户点踩示例：

{
  "question": "统计每个部门的员工数量",
  "sql": "SELECT department, COUNT(*) FROM employees",
  "is_thumb_up": false,
  "user_id": "user456"
}

✅ 成功响应格式

{
    "code": 200,
    "data": {
        "feedback_id": 18,
        "response": "反馈记录创建成功"
    },
    "message": "操作成功",
    "success": true
}

6. 反馈统计信息 API

端点: GET /api/v0/qa_feedback/stats

功能: 获取反馈数据的统计信息，用于监控面板和数据分析。

🌰 请求示例

GET /api/v0/qa_feedback/stats

✅ 成功响应格式

{
    "code": 200,
    "data": {
        "response": "统计信息获取成功",
        "total_feedback": 18,
        "positive_feedback": 8,
        "negative_feedback": 10,
        "trained_feedback": 5,
        "untrained_feedback": 13,
        "positive_rate": 44.44,
        "training_rate": 27.78
    },
    "message": "操作成功",
    "success": true
}

📊 统计字段说明

字段名	说明
`total_feedback`	总反馈数
`positive_feedback`	正向反馈数（点赞）
`negative_feedback`	负向反馈数（点踩）
`trained_feedback`	已训练反馈数
`untrained_feedback`	未训练反馈数
`positive_rate`	正向反馈率（%）
`training_rate`	训练覆盖率（%）

🔧 使用流程示例

典型工作流程

用户反馈阶段

POST /api/v0/qa_feedback/add
{
 "question": "查询用户订单",
 "sql": "SELECT * FROM orders WHERE user_id = 123",
 "is_thumb_up": true,
 "user_id": "user123"
}

审核管理阶段 json POST /api/v0/qa_feedback/query { "is_in_training_data": false, "page": 1, "page_size": 50 }

批量训练阶段

POST /api/v0/qa_feedback/add_to_training
{
 "feedback_ids": [1, 2, 3, 4, 5]
}

统计监控阶段 ```

GET /api/v0/qa_feedback/stats


---

## ⚠️ 错误处理

### 常见错误响应

**400 - 请求参数错误**
```json
{
  "code": 400,
  "success": false,
  "message": "请求参数错误",
  "data": {
    "response": "缺少必需参数：question",
    "missing_params": ["question"],
    "error_type": "missing_required_params",
    "timestamp": "2024-06-24T10:30:00"
  }
}

404 - 资源未找到

{
  "code": 404,
  "success": false,
  "message": "资源未找到",
  "data": {
    "response": "反馈记录不存在 (ID: 999)",
    "error_type": "resource_not_found",
    "timestamp": "2024-06-24T10:30:00"
  }
}

500 - 系统内部错误

{
  "code": 500,
  "success": false,
  "message": "系统内部错误",
  "data": {
    "response": "查询反馈记录失败，请稍后重试",
    "error_type": "database_error",
    "can_retry": true,
    "timestamp": "2024-06-24T10:30:00"
  }
}

🚀 Postman 测试集合

环境变量

{
  "base_url": "http://localhost:8084",
  "api_prefix": "/api/v0/qa_feedback"
}

测试用例建议

数据创建测试 - 先添加几条反馈记录
查询功能测试 - 测试各种筛选和排序组合
更新功能测试 - 修改记录内容
训练集成测试 - 批量添加到训练数据
统计功能测试 - 验证统计数据准确性
删除功能测试 - 清理测试数据

📝 注意事项

数据库自动创建: 首次调用任何API时，系统会自动创建 qa_feedback 表
连接复用: 系统优先复用现有的Vanna数据库连接，提高性能
事务安全: 所有写操作都使用数据库事务，确保数据一致性
分页限制: 查询API的 page_size 最大值为100，避免单次返回过多数据
训练幂等性: 同一记录不会重复训练，系统会自动跟踪训练状态

🎯 总结

QA反馈模块提供了完整的反馈数据生命周期管理，从用户反馈收集到训练数据集成，支持高效的数据处理和智能的训练优化。通过合理使用这些API，可以构建强大的用户反馈系统，持续改进AI模型的表现。

QA反馈模块API调用说明.md 13 KB Geçmiş Ham

QA反馈模块API调用说明

📋 概述

🔧 基础信息

🔍 API端点一览

📖 详细API说明

1. 查询反馈记录 API

📝 请求参数

🌰 请求示例

✅ 成功响应格式

2. 删除反馈记录 API

📝 路径参数

🌰 请求示例

✅ 成功响应格式

❌ 失败响应格式

3. 修改反馈记录 API

📝 路径参数

📝 请求参数

🌰 请求示例

✅ 成功响应格式

4. 添加到训练数据集 API ⭐

📝 请求参数

🌰 请求示例

✅ 成功响应格式

🔄 处理逻辑说明

5. 创建反馈记录 API

📝 请求参数

🌰 请求示例

✅ 成功响应格式

6. 反馈统计信息 API

🌰 请求示例

✅ 成功响应格式

📊 统计字段说明

🔧 使用流程示例

典型工作流程

🚀 Postman 测试集合

环境变量

测试用例建议

📝 注意事项

🎯 总结

QA反馈模块API调用说明.md 13 KB

Geçmiş Ham