Redis 对话管理 API 文档

概述

辞图智能数据问答平台提供了完整的基于 Redis 的对话管理功能，支持多用户、多会话的智能问答场景。本文档详细介绍了所有与 Redis 对话管理相关的 API 接口。

API 基础信息

基础URL: http://localhost:8084
Content-Type: application/json
响应格式: 标准化的JSON响应格式

API 列表

1. 获取用户对话列表

接口信息

URL: /api/v0/user/{user_id}/conversations
方法: GET
功能: 获取指定用户的对话列表，按时间倒序排列

请求参数

参数名	类型	位置	必填	说明
user_id	string	路径参数	是	用户ID
limit	integer	查询参数	否	最大返回数量，默认为 USER_MAX_CONVERSATIONS

请求示例

GET /api/v0/user/john_doe/conversations?limit=10

响应示例

{
    "success": true,
    "code": 200,
    "message": "获取用户对话列表成功",
    "data": {
        "user_id": "john_doe",
        "conversations": [
            {
                "conversation_id": "conv_20241201_001",
                "start_time": "2024-12-01T10:00:00",
                "last_activity": "2024-12-01T10:30:00",
                "message_count": 6
            }
        ],
        "total_count": 1
    }
}

2. 获取对话消息历史

接口信息

URL: /api/v0/conversation/{conversation_id}/messages
方法: GET
功能: 获取特定对话的所有消息历史

请求参数

参数名	类型	位置	必填	说明
conversation_id	string	路径参数	是	对话ID
limit	integer	查询参数	否	最大返回消息数量

请求示例

GET /api/v0/conversation/conv_20241201_001/messages?limit=50

响应示例

{
    "success": true,
    "code": 200,
    "message": "获取对话消息成功",
    "data": {
        "conversation_id": "conv_20241201_001",
        "conversation_meta": {
            "created_at": "2024-12-01T10:00:00",
            "message_count": 6
        },
        "messages": [
            {
                "role": "user",
                "content": "查询销售数据",
                "timestamp": "2024-12-01T10:00:00",
                "metadata": {}
            },
            {
                "role": "assistant",
                "content": "好的，我来帮您查询销售数据...",
                "timestamp": "2024-12-01T10:00:05",
                "metadata": {
                    "type": "DATABASE",
                    "sql": "SELECT * FROM sales"
                }
            }
        ],
        "message_count": 6
    }
}

3. 获取对话上下文

接口信息

URL: /api/v0/conversation/{conversation_id}/context
方法: GET
功能: 获取对话上下文，格式化用于 LLM 处理

请求参数

参数名	类型	位置	必填	说明
conversation_id	string	路径参数	是	对话ID
count	integer	查询参数	否	上下文消息数量，默认为 CONVERSATION_CONTEXT_COUNT

请求示例

GET /api/v0/conversation/conv_20241201_001/context?count=5

响应示例

{
    "success": true,
    "code": 200,
    "message": "获取对话上下文成功",
    "data": {
        "conversation_id": "conv_20241201_001",
        "context": "User: 查询销售数据\nAssistant: 好的，我来帮您查询销售数据...\nUser: 能否按月份分组？",
        "context_message_count": 5
    }
}

4. 获取用户完整对话数据 🆕

接口信息

URL: /api/v0/user/{user_id}/conversations/full
方法: GET
功能: 一次性获取用户的所有对话和每个对话下的消息历史

请求参数

参数名	类型	位置	必填	说明
user_id	string	路径参数	是	用户ID
conversation_limit	integer	查询参数	否	对话数量限制，不传则返回所有对话
message_limit	integer	查询参数	否	每个对话的消息数限制，不传则返回所有消息

请求示例

# 获取所有对话和消息
GET /api/v0/user/john_doe/conversations/full

# 限制返回数据量
GET /api/v0/user/john_doe/conversations/full?conversation_limit=50&message_limit=100

# 只限制对话数量
GET /api/v0/user/john_doe/conversations/full?conversation_limit=20

响应示例

{
    "success": true,
    "code": 200,
    "message": "获取用户完整对话数据成功",
    "data": {
        "user_id": "john_doe",
        "conversations": [
            {
                "conversation_id": "conv_20241201_001",
                "start_time": "2024-12-01T10:00:00",
                "last_activity": "2024-12-01T10:30:00",
                "meta": {
                    "message_count": 6,
                    "created_at": "2024-12-01T10:00:00"
                },
                "messages": [
                    {
                        "role": "user",
                        "content": "查询销售数据",
                        "timestamp": "2024-12-01T10:00:00"
                    },
                    {
                        "role": "assistant",
                        "content": "好的，我来帮您查询销售数据...",
                        "timestamp": "2024-12-01T10:00:05"
                    }
                ],
                "message_count": 6
            }
        ],
        "total_conversations": 1,
        "total_messages": 6,
        "conversation_limit_applied": null,
        "message_limit_applied": null,
        "query_time": "2024-12-01T15:30:00"
    }
}

5. 获取对话系统统计信息

接口信息

URL: /api/v0/conversation_stats
方法: GET
功能: 获取 Redis 对话系统的统计信息

请求参数

无

请求示例

GET /api/v0/conversation_stats

响应示例

{
    "success": true,
    "code": 200,
    "message": "获取统计信息成功",
    "data": {
        "total_users": 125,
        "total_conversations": 1250,
        "total_messages": 5000,
        "active_users_today": 45,
        "active_conversations_today": 200,
        "cache_hit_rate": 0.75,
        "redis_info": {
            "connected": true,
            "memory_usage": "120MB",
            "keys_count": 2500
        }
    }
}

6. 清理过期对话

接口信息

URL: /api/v0/conversation_cleanup
方法: POST
功能: 手动清理 Redis 中的过期对话数据

请求参数

无

请求示例

POST /api/v0/conversation_cleanup

响应示例

{
    "success": true,
    "code": 200,
    "message": "对话清理完成",
    "data": {
        "cleaned_conversations": 50,
        "cleaned_messages": 200,
        "cleanup_time": "2024-12-01T15:30:00"
    }
}

7. 智能问答（支持对话上下文）

接口信息

URL: /api/v0/ask_agent
方法: POST
功能: 支持对话上下文的智能问答接口，集成 Redis 对话管理

请求参数

参数名	类型	位置	必填	说明
question	string	请求体	是	用户问题
session_id	string	请求体	否	浏览器会话ID
user_id	string	请求体	否	用户ID
conversation_id	string	请求体	否	对话ID
continue_conversation	boolean	请求体	否	是否继续现有对话

请求示例

POST /api/v0/ask_agent
Content-Type: application/json

{
    "question": "查询最近一个月的销售数据",
    "session_id": "session_12345",
    "user_id": "john_doe",
    "continue_conversation": true
}

响应示例

{
    "success": true,
    "code": 200,
    "message": "查询执行完成",
    "data": {
        "type": "DATABASE",
        "response": "",
        "sql": "SELECT * FROM sales WHERE date >= DATE_SUB(NOW(), INTERVAL 1 MONTH)",
        "query_result": {
            "rows": [...],
            "columns": ["date", "amount", "product"],
            "row_count": 150,
            "total_row_count": 150,
            "is_limited": false
        },
        "summary": "查询到最近一个月的销售数据共150条记录...",
        "session_id": "session_12345",
        "execution_path": ["classify_question", "generate_sql", "execute_sql", "generate_summary"],
        "classification_info": {
            "question_type": "DATABASE",
            "confidence": 0.95,
            "method": "rule_based_database_keywords"
        },
        "conversation_id": "conv_20241201_002",
        "user_id": "john_doe",
        "is_guest_user": false,
        "context_used": true,
        "from_cache": false,
        "conversation_status": "continued",
        "conversation_message": "继续现有对话"
    }
}

Redis 对话管理特性

1. 用户身份管理

支持登录用户和访客用户
基于 session_id 和 IP 地址的访客识别
智能用户ID解析和会话管理

2. 对话生命周期管理

自动创建和管理对话
支持对话继续和新建
对话元数据维护和更新

3. 上下文管理

维护对话历史和上下文
支持上下文感知的问答
灵活的上下文长度控制

4. 缓存机制

智能答案缓存和检索
只缓存无上下文的问答，避免上下文污染
缓存命中率统计和性能优化

5. 数据持久化

Redis 数据持久化存储
自动过期和清理机制
数据备份和恢复支持

错误处理

所有 API 都遵循统一的错误响应格式：

{
    "success": false,
    "code": 500,
    "message": "处理失败",
    "data": {
        "error": "具体错误信息",
        "error_type": "error_type_code",
        "can_retry": true,
        "timestamp": "2024-12-01T15:30:00"
    }
}

常见错误码

错误码	说明
400	请求参数错误
422	参数验证失败
500	系统内部错误
503	服务暂时不可用

使用建议

1. 性能优化

合理使用分页参数控制返回数据量
使用缓存机制减少重复查询
定期清理过期对话数据

2. 安全考虑

验证用户权限和会话有效性
避免暴露敏感的对话内容
实施适当的访问频率限制

3. 最佳实践

使用 /conversations/full API 获取完整数据
根据业务需求设置合理的上下文长度
监控 Redis 内存使用情况

配置参数

相关配置参数在 app_config.py 中定义：

# Redis 对话管理配置
USER_MAX_CONVERSATIONS = 50        # 用户最大对话数
CONVERSATION_CONTEXT_COUNT = 10    # 默认上下文消息数量
REDIS_CONVERSATION_TTL = 86400 * 7 # 对话过期时间（7天）

缓存策略说明

智能缓存机制

系统采用上下文感知的缓存策略：

缓存规则

✅ 缓存存储条件: 只有无上下文的问答会被缓存（严控质量）
✅ 缓存使用条件: 无论是否有上下文都可以查找缓存（提高利用率）

缓存逻辑

第1次问答（无上下文）→ 缓存存储 ✅
第2次相同问题（有上下文）→ 缓存命中 ✅（优化后）
第3次相同问题（新对话，无上下文）→ 缓存命中 ✅

优势

🎯 缓存质量保障: 严控存储条件，确保缓存都是明确的问答
⚡ 性能全面提升: 新用户和多轮对话都能享受缓存加速
🧠 平衡设计: 存储严格，使用灵活，错误概率低
🔄 高利用率: 最大化缓存的使用价值

配置控制

# 在 app_config.py 中控制缓存行为
ENABLE_QUESTION_ANSWER_CACHE = True  # 全局缓存开关
QUESTION_ANSWER_TTL = 24 * 3600      # 缓存过期时间（24小时）

更新日志

v1.2.1 (2024-12-22)

🚀 平衡缓存策略: 严控存储条件，放宽使用条件
⚡ 性能提升: 多轮对话中的重复问题也能使用缓存
🎯 智能平衡: 既保证缓存质量，又最大化利用率

v1.2.0 (2024-12-22)

🔧 优化缓存策略: 只缓存无上下文的问答，避免上下文污染
✨ 简化缓存键: 基于问题本身生成缓存键，提高缓存命中率
🎯 逻辑优化: 解决同一对话中重复问题无法使用缓存的问题

v1.1.0 (2024-12-01)

🆕 新增 /api/v0/user/{user_id}/conversations/full API
✨ 支持一次性获取用户完整对话数据
🔧 优化参数处理，支持不传递限制参数时返回所有记录

v1.0.0 (2024-11-01)

🎉 首次发布 Redis 对话管理功能
📝 完整的 API 文档和使用指南

Redis对话管理API文档.md 13 KB Riwayat Mentahan

Redis 对话管理 API 文档

概述

API 基础信息

API 列表

1. 获取用户对话列表

接口信息

请求参数

请求示例

响应示例

2. 获取对话消息历史

接口信息

请求参数

请求示例

响应示例

3. 获取对话上下文

接口信息

请求参数

请求示例

响应示例

4. 获取用户完整对话数据 🆕

接口信息

请求参数

请求示例

响应示例

5. 获取对话系统统计信息

接口信息

请求参数

请求示例

响应示例

6. 清理过期对话

接口信息

请求参数

请求示例

响应示例

7. 智能问答（支持对话上下文）

接口信息

请求参数

请求示例

响应示例

Redis 对话管理特性

1. 用户身份管理

2. 对话生命周期管理

3. 上下文管理

4. 缓存机制

5. 数据持久化

错误处理

常见错误码

使用建议

1. 性能优化

2. 安全考虑

3. 最佳实践

配置参数

缓存策略说明

智能缓存机制

缓存规则

缓存逻辑

优势

配置控制

更新日志

v1.2.1 (2024-12-22)

v1.2.0 (2024-12-22)

v1.1.0 (2024-12-01)

v1.0.0 (2024-11-01)

Redis对话管理API文档.md 13 KB

Riwayat Mentahan