wangxiaoqing_citu/citu_vanna

ask_agent()

ask_agent()用来代替原来的ask() API，它采用LLM Agent技术，支持混合对话，即数据库查询和自由对话模式。

API端点一览

|API端点|方法|功能描述| |-|-|-| |/api/v0/ask_agent|POST|智能问答查询（支持数据库查询和自由对话）|

1.1.成功生成SQL并执行查询

POST http://localhost:8084/api/v0/ask_agent

{
    "question": "请按照收入给每个高速服务区进行排名？返回收入最多的前三名服务区？"
}

#正常生成SQL,并完成查询的返回结果

{
    "code": 200,
    "data": {
        "agent_version": "langgraph_v1",
        "classification_info": {
            "confidence": 0.9,
            "method": "rule_based_strong_business",
            "reason": "强业务特征 - 业务实体: ['核心业务实体:服务区', '支付业务:收入'], 查询意图: ['排名'], SQL: []"
        },
        "context_used": false,
        "conversation_id": "conv_1751199617_5d37a647",
        "conversation_message": "创建新对话",
        "conversation_status": "new",
        "execution_path": [
            "start",
            "classify",
            "agent_sql_generation",
            "agent_sql_execution",
            "format_response"
        ],
        "from_cache": false,
        "is_guest_user": true,
        "records": {
            "columns": [
                "服务区名称",
                "总收入"
            ],
            "is_limited": false,
            "row_count": 3,
            "rows": [
                {
                    "总收入": "7024226.1500",
                    "服务区名称": "庐山服务区"
                },
                {
                    "总收入": "6929288.3300",
                    "服务区名称": "三清山服务区"
                },
                {
                    "总收入": "6848435.6700",
                    "服务区名称": "南城服务区"
                }
            ],
            "total_row_count": 3
        },
        "response": "根据收入排名，前三名高速服务区依次为：庐山服务区（702.42万元）、三清山服务区（692.93万元）、南城服务区（684.84万元）。",
        "routing_mode_source": "config",
        "routing_mode_used": "hybrid",
        "session_id": null,
        "sql": "SELECT service_name AS 服务区名称, SUM(pay_sum) AS 总收入 \nFROM bss_business_day_data \nWHERE delete_ts IS NULL \nGROUP BY service_name \nORDER BY 总收入 DESC NULLS LAST \nLIMIT 3;",
        "summary": "根据收入排名，前三名高速服务区依次为：庐山服务区（702.42万元）、三清山服务区（692.93万元）、南城服务区（684.84万元）。",
        "timestamp": "2025-06-29T20:20:56.806141",
        "type": "DATABASE",
        "user_id": "guest"
    },
    "message": "操作成功",
    "success": true
}

前端UI应关注的参数：

1."response": 它将代替原来的summary，会查询的结果进行总结。

2."sql"：执行查询SQL.

3."data.records"：查询返回的数据，包括表头(data.records.columns)和数据行(data.records.rows)

1.2.未成功生成SQL

POST http://localhost:8084/api/v0/ask_agent

{
    "question": "请问每个高速公路服务区的管理经理是谁？"

}

# 返回结果
{
    "code": 200,
    "data": {
        "agent_version": "langgraph_v1",
        "classification_info": {
            "confidence": 0.82,
            "method": "rule_based_medium_business",
            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:高速公路']"
        },
        "context_used": false,
        "conversation_id": "conv_1751201276_e59f0a07",
        "conversation_message": "创建新对话",
        "conversation_status": "new",
        "execution_path": [
            "start",
            "classify",
            "agent_sql_generation",
            "format_response"
        ],
        "from_cache": false,
        "is_guest_user": true,
        "response": "当前提供的上下文信息不足以生成查询服务区对应管理经理的SQL语句。原因如下：\n\n1. 在服务区管理公司表(bss_company)中虽然存在created_by/updated_by字段，但这些字段仅记录数据操作者（系统用户），而非实际的管理经理人员信息。\n\n2. 现有表结构中缺失以下关键实体：\n   - 员工/人员信息表（存储经理姓名等个人信息）\n   - 公司与人员的组织架构表（关联公司ID与员工ID）\n\n3. 当前表间关系仅能查询到服务区所属的管理公司名称（通过bss_service_area.company_id关联bss_company.id），但无法获取具体管理人员的姓名。\n\n需要补充以下信息才能继续：\n- 存储人员信息的表结构（特别是管理岗位人员）\n- 公司与人员的关联关系表结构 请尝试提问其它问题。",
        "routing_mode_source": "config",
        "routing_mode_used": "hybrid",
        "session_id": null,
        "timestamp": "2025-06-29T20:48:21.351324",
        "type": "DATABASE",
        "user_id": "guest"
    },
    "message": "操作成功",
    "success": true
}

前端UI应关注的参数：

1.没有返回"sql"和"data.records"。

2."response":当没有返回"sql"和"data.records"的时候，response会返回未能生成SQL的原因，可以返回给客户端。

1.3.在Post中传递路由参数

当Post 参数中，没有包含routing_mode 参数时，默认会采用服务配置文件app_config.py中"QUESTION_ROUTING_MODE "参数，它的默认值是"hybrid"。

这个routing_mode 参数的含义是，手工调整查询数据库或自由对话的路由。例如，当我们在切换话题时，如果LLM不能及时的从数据库查询/自由对话模式路由到正确模式，那么需要通过传递这个参数来强迫系统查询数据库，或自由对话。它为对话提供一个兜底方案。

我们可以在对话框的下方或者右侧合适的位置，添加两个按钮"数据查询模式"和"自由对话模式"，当点击"数据查询模式时"，在POST参数中自动添加"routing_mode: database_direct"，当点击"自由对话模式"，在POST参数中自动添加"routing_mode: chat_direct".

routing_mode (string, 可选)
问题路由模式，控制AI如何处理问题
有效值：
- "database_direct": 直接数据库查询模式
- "chat_direct": 直接聊天模式

举例说明：

POST http://localhost:8084/api/v0/ask_agent

下面的例子，如果不添加 "routing_mode": "database_direct"，这个问题会被路由到自由查询模式，因为数据库中没有充电桩的数据。但 "routing_mode": "database_direct" 参数会强迫系统查询数据库。

{
    "question": "请问中国共有多少个充电桩",
    "routing_mode": "database_direct"

}

# 上面的参数，返回结果：

{
    "code": 200,
    "data": {
        "agent_version": "langgraph_v1",
        "classification_info": {
            "confidence": 1,
            "method": "direct_database",
            "reason": "配置为直接数据库查询模式"
        },
        "context_used": false,
        "conversation_id": "conv_1751202425_d04139e4",
        "conversation_message": "创建新对话",
        "conversation_status": "new",
        "execution_path": [
            "start",
            "init_direct_database",
            "agent_sql_generation",
            "format_response"
        ],
        "from_cache": false,
        "is_guest_user": true,
        "response": "提供的上下文未包含充电桩相关数据字段，无法统计中国充电粧总数。当前数据库中服务区相关表（bss_service_area）未记录充电粧数量信息，建议确认业务表结构或补充数据来源。 请尝试提问其它问题。",
        "routing_mode_source": "api",
        "routing_mode_used": "database_direct",
        "session_id": null,
        "timestamp": "2025-06-29T21:07:26.383228",
        "type": "DATABASE",
        "user_id": "guest"
    },
    "message": "操作成功",
    "success": true
}

1.4. 关于用户认证

按照项目组的约定，将来会从Post中获取token令牌，然后通过API获取user_id。在当前系统中，暂时没有提供用户验证功能。出于测试目的可以传递user_id，不同的user_id会看到属于自己的对话记录。

如果没有传递user_id，那么将使用默认用户guest.

POST http://localhost:8084/api/v0/ask_agent

{
    "question": "请问中国共有多少个充",
    "user_id": "Paul"
}

1.5.关于上下文对话的传递(多轮对话)

每个用户user_id，默认会保存最近5次的"会话"(conversation_id)，每个conversation_id会保存10组对话信息。每次上下文传递默认会传递最近2次的对话上下文。

这些参数在app_config.py中进行控制：

# app_config.py 的对话上下文配置
CONVERSATION_CONTEXT_COUNT = 2          # 传递给LLM的上下文消息条数
CONVERSATION_MAX_LENGTH = 10            # 单个对话最大消息数
USER_MAX_CONVERSATIONS = 5              # 用户最大对话数

第一轮对话：

POST http://localhost:8084/api/v0/ask_agent

{
    "question": "请问哪个服务区的档口最多？",
    "user_id": "Paul"
}

# 请注意在下面的返回的结果中，包含了 "data.conversation_id",
# "conversation_id": "conv_1751205549_308eb7c3",

{
    "code": 200,
    "data": {
        "agent_version": "langgraph_v1",
        "classification_info": {
            "confidence": 0.82,
            "method": "rule_based_medium_business",
            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:档口']"
        },
        "context_used": false,
        "conversation_id": "conv_1751205549_308eb7c3",
        "conversation_message": "创建新对话",
        "conversation_status": "new",
        "execution_path": [
            "start",
            "classify",
            "agent_sql_generation",
            "agent_sql_execution",
            "format_response"
        ],
        "from_cache": false,
        "is_guest_user": false,
        "records": {
            "columns": [
                "服务区名称",
                "档口数量"
            ],
            "is_limited": false,
            "row_count": 1,
            "rows": [
                {
                    "服务区名称": "南城服务区",
                    "档口数量": 39
                }
            ],
            "total_row_count": 1
        },
        "response": "南城服务区的档口数量最多，共计39个。",
        "routing_mode_source": "config",
        "routing_mode_used": "hybrid",
        "session_id": null,
        "sql": "SELECT sa.service_area_name AS 服务区名称, COUNT(b.id) AS 档口数量 FROM bss_service_area sa JOIN bss_branch b ON sa.id = b.service_area_id WHERE sa.delete_ts IS NULL AND b.delete_ts IS NULL GROUP BY sa.service_area_name ORDER BY 档口数量 DESC NULLS LAST LIMIT 1;",
        "summary": "南城服务区的档口数量最多，共计39个。",
        "timestamp": "2025-06-29T22:00:17.154155",
        "type": "DATABASE",
        "user_id": "Paul"
    },
    "message": "操作成功",
    "success": true
}

请前端UI关注"conversation_id": "conv_1751205549_308eb7c3"，当第二次或后续再次提交POST的时候，传递相同的"user_id"和"conversation_id"，后台服务就会把相同的"conversation_id"作为一次会话保存。再提交问题给LLM的时候，会把前面两次对话记录传递给LLM。

第二轮对话，注意POST参数中提供了第一轮对话中返回的"conversation_id"，然后在第二个问题中延续了第一个问题中的答案。

POST http://localhost:8084/api/v0/ask_agent

{
    "conversation_id": "conv_1751205549_308eb7c3",
    "question": "请问这个服务区的餐饮档口有几个？",
    "user_id": "Paul"
}

# 返回结果
{
    "code": 200,
    "data": {
        "agent_version": "langgraph_v1",
        "classification_info": {
            "confidence": 0.8799999999999999,
            "method": "rule_based_medium_business",
            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:档口', '经营品类:餐饮']"
        },
        "context_used": true,
        "conversation_id": "conv_1751205549_308eb7c3",
        "conversation_message": "继续已有对话",
        "conversation_status": "existing",
        "execution_path": [
            "start",
            "classify",
            "agent_sql_generation",
            "agent_sql_execution",
            "format_response"
        ],
        "from_cache": false,
        "is_guest_user": false,
        "records": {
            "columns": [
                "餐饮档口数量"
            ],
            "is_limited": false,
            "row_count": 1,
            "rows": [
                {
                    "餐饮档口数量": 6
                }
            ],
            "total_row_count": 1
        },
        "response": "该服务区餐饮档口数量为6个。",
        "routing_mode_source": "config",
        "routing_mode_used": "hybrid",
        "session_id": null,
        "sql": "SELECT COUNT(*) AS 餐饮档口数量 FROM bss_branch b JOIN bss_service_area sa ON b.service_area_id = sa.id WHERE sa.service_area_name = '南城服务区' AND b.classify = '餐饮' AND b.delete_ts IS NULL;",
        "summary": "该服务区餐饮档口数量为6个。",
        "timestamp": "2025-06-29T22:09:25.494134",
        "type": "DATABASE",
        "user_id": "Paul"
    },
    "message": "操作成功",
    "success": true
}

在debug的时候，可以注意上面的返回参数中"conversation_message"和 "conversation_status"在第一轮对话和第二轮对话中的值是不同的：

第一轮对话：

    `"conversation_message": "创建新对话",`
    `"conversation_status": "new",`

第二轮对话：

    `"conversation_message": "继续已有对话",`
   ` "conversation_status": "existing",`

1.ask_agent API 说明.md 14 KB 永久連結 文件歷史 原始文件

ask_agent()

API端点一览

1.1.成功生成SQL并执行查询

1.2.未成功生成SQL

1.3.在Post中传递路由参数

1.4. 关于用户认证

1.5.关于上下文对话的传递(多轮对话)

1.ask_agent API 说明.md 14 KB

永久連結文件歷史原始文件