## 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](http://localhost:8084/api/v0/ask_agent) ```JSON { "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](http://localhost:8084/api/v0/ask_agent) ```JSON { "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". ```Markdown routing_mode (string, 可选) 问题路由模式，控制AI如何处理问题 有效值： - "database_direct": 直接数据库查询模式 - "chat_direct": 直接聊天模式 ``` 举例说明： POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent) 下面的例子，如果不添加 "routing_mode": "database_direct"，这个问题会被路由到自由查询模式，因为数据库中没有充电桩的数据。但 "routing_mode": "database_direct" 参数会强迫系统查询数据库。 ```JSON { "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](http://localhost:8084/api/v0/ask_agent) ```JSON { "question": "请问中国共有多少个充", "user_id": "Paul" } ``` ### 1.5.关于上下文对话的传递(多轮对话) 每个用户user_id，默认会保存最近5次的"会话"(conversation_id)，每个conversation_id会保存10组对话信息。每次上下文传递默认会传递最近2次的对话上下文。 这些参数在app_config.py中进行控制： ```Python # app_config.py 的对话上下文配置 CONVERSATION_CONTEXT_COUNT = 2 # 传递给LLM的上下文消息条数 CONVERSATION_MAX_LENGTH = 10 # 单个对话最大消息数 USER_MAX_CONVERSATIONS = 5 # 用户最大对话数 ``` **第一轮对话**： POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent) ```JSON { "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](http://localhost:8084/api/v0/ask_agent) ```JSON { "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",`