基于Claude Code与SQLite的自然语言转SQL查询助手实战

1. 项目概述：当自然语言遇见数据库查询

最近在折腾一个挺有意思的东西，我把它叫做“自然语言查库助手”。简单来说，就是让一个AI模型，比如Claude Code，能听懂你用大白话问的问题，然后自动帮你生成正确的SQL语句，去数据库里把你要的数据捞出来。这听起来是不是有点像科幻电影里的场景？但说实话，现在这技术已经相当实用了，尤其是在数据分析、产品运营或者日常业务查询这些场景里，能省下大量写SQL、调试SQL的时间。

我自己在工作中就经常遇到这种情况：产品经理或者业务同事跑过来问，“帮我查一下上个月注册用户里，付费转化率超过5%的是哪些渠道？” 或者 “看看最近一周活跃度下降的用户，他们的主要行为特征是什么？”。对于我这种天天跟SQL打交道的人来说，可能花几分钟就能写出一个JOIN加WHERE再加GROUP BY的复杂查询。但对于不熟悉SQL的同事，或者我自己在赶时间、思路不清晰的时候，这个过程就变得很痛苦。你需要理解业务逻辑，转换成数据库的表结构，再精确地写出语法正确的SQL，任何一个环节出错，结果就南辕北辙。

所以，这个“自然语言查库助手”的核心价值就出来了：降低数据获取的门槛，提升信息流转的效率。它充当了一个“翻译官”的角色，把人类模糊的、基于业务逻辑的自然语言指令，翻译成计算机能精确执行的、结构化的SQL查询语言。这次我选择用Claude Code这个模型来搭建，主要是看中了它在代码生成和理解任务上的突出能力，以及相对友好的部署和调试环境。后端数据库则用了SQLite，因为它轻量、无需独立服务进程，一个文件就是一个数据库，特别适合做原型验证和中小型数据场景。

这个项目（上篇）会聚焦在最核心的链路打通上：如何搭建环境，如何设计一个基础但有效的提示词（Prompt），让Claude Code理解我们的数据库结构并生成可执行的SQL，最后如何安全地执行查询并返回结果。我们会避开那些花哨的界面，先用最朴素的命令行方式把核心逻辑跑通，理解每一个环节的原理和可能踩的坑。毕竟，地基打牢了，后面加什么功能都容易。

2. 核心思路与方案选型：为什么是Claude Code + SQLite？

在动手之前，我们得先想清楚技术栈怎么选。市面上能做文本生成代码的模型不止一个，数据库也琳琅满目，为什么我最终拍板用了Claude Code和SQLite这个组合？这里面的考量，其实是一次在能力、复杂度、成本和效率之间的权衡。

2.1 模型选择：Claude Code的独特优势

首先看模型侧。我们需要的核心能力是“自然语言转SQL”（Text-to-SQL）。这不是简单的文本续写，它要求模型具备：

1. 对自然语言深层意图的理解能力：能分辨“销量最好的产品”和“销售额最高的产品”之间的细微差别。
2. 对数据库模式（Schema）的理解和关联能力：知道“用户”对应users表，“订单”对应orders表，并且能通过user_id字段进行关联。
3. 精确的SQL语法生成能力：生成的代码必须语法正确，能直接执行。

基于这些要求，我评估了几个选项：

• 通用大语言模型（如GPT系列）：能力很强，但通常需要调用API，涉及网络延迟、费用成本，并且对于企业内部可能敏感的数据库结构，将Schema发送到云端存在数据安全顾虑。
• 一些开源的代码生成模型：虽然可以本地部署，但它们在专门的自然语言理解，特别是结合特定上下文（如数据库Schema）进行推理的能力上，可能不如专门的模型。
• Claude Code：它吸引我的点在于几个方面。首先，它被宣传为在代码生成和与代码相关的对话任务上进行了深度优化。其次，根据其设计思路，它对于“指令跟随”和“上下文学习”应该比较擅长，这正是我们设计Prompt时所依赖的核心机制。最后，虽然它可能也需要一定的环境配置，但其定位更贴近我们“代码助手”的场景，预期它对于“根据表结构生成查询语句”这类任务会有更好的表现。

注意：模型的选择并非一成不变。Claude Code在这里作为一个具体的技术载体，我们更应关注的是实现这套逻辑的方法论。未来如果有了更强大、更易用的本地模型，我们可以用同样的架构思路进行替换。

2.2 数据库选择：SQLite的轻量之道

再来看数据库侧。对于这样一个原型或轻量级助手，选型原则是：简单、内嵌、零管理。

• MySQL/PostgreSQL：功能强大，但需要独立安装、配置服务、管理用户权限，对于快速验证想法来说太重了。
• SQLite：完美契合需求。它是一个进程内的库，整个数据库就是一个文件（比如mydatabase.db）。无需配置服务器，通过程序直接读写文件即可。Python标准库就内置了sqlite3模块，开箱即用。这对于演示、开发测试、或者处理百万级别以下数据量的个人/小组应用来说，性能完全足够。

更重要的是，SQLite的sqlite_master表可以很方便地查询到所有表、视图的结构（即Schema），这为我们动态获取数据库信息、并将其注入给AI模型提供了便利。我们不需要手动维护一份独立的Schema文档，程序可以自己“看”懂数据库。

2.3 整体架构设计

基于以上选型，我们的系统架构就非常清晰了，核心流程是一个闭环：

1. 输入：用户用自然语言提出查询问题，例如：“计算每个部门上个月的平均工资”。
2. 上下文构建：程序动态连接到SQLite数据库，提取相关表的Schema信息（表名、字段名、字段类型）。
3. 提示词工程：将Schema信息和用户问题，按照精心设计的模板，组合成一个完整的“提示词”（Prompt），提交给Claude Code模型。
4. AI推理：Claude Code模型接收提示词，理解数据库结构和用户意图，生成对应的SQL查询语句。
5. 执行与反馈：程序安全地执行生成的SQL语句（这里必须加入安全限制，比如只允许SELECT查询），从SQLite数据库中获取结果。
6. 输出：将查询结果以易于阅读的格式（如表格）返回给用户。

这个流程中，最核心、也最需要精心打磨的环节就是第3步——提示词工程。它直接决定了AI模型是否能正确理解任务并输出可靠的SQL。我们接下来会重点剖析。

3. 环境搭建与核心工具链配置

工欲善其事，必先利其器。在开始写代码之前，我们需要一个干净、可复现的工作环境。这里我假设你使用的是macOS或Linux系统（Windows用户使用WSL或Git Bash也能获得类似体验），并且已经具备了基本的Python环境。

3.1 Python虚拟环境与依赖管理

强烈建议使用虚拟环境来隔离项目依赖，避免污染系统级的Python库。

# 1. 为项目创建一个新的目录 mkdir claude_code_sql_assistant && cd claude_code_sql_assistant # 2. 创建Python虚拟环境（这里使用Python3内置的venv模块） python3 -m venv venv # 3. 激活虚拟环境 # 在macOS/Linux上： source venv/bin/activate # 激活后，命令行提示符前通常会显示 (venv) # 4. 安装核心依赖 # 我们将使用openai库的兼容模式来调用Claude Code（如果其提供兼容API）， # 同时需要sqlite3（通常内置）和tabulate用于美化输出。 # 假设Claude Code可通过类似OpenAI的API访问，我们先安装openai库。 # 实际中，请根据Claude Code提供的具体SDK安装。 pip install openai sqlite-utils tabulate # 如果Claude Code有专门的Python包，则应安装其官方包，例如： # pip install anthropic

这里解释一下几个依赖包：

• openai/anthropic：用于与AI模型的API进行交互。关键点在于：你需要根据Claude Code模型服务方提供的具体接入方式来选择正确的SDK。如果是兼容OpenAI API的，就用openai库；如果是Anthropic自家的，就用anthropic库。这一步是后续能调通API的基础。
• sqlite-utils：一个非常强大的SQLite工具库，它提供了比标准sqlite3模块更友好、功能更丰富的接口，例如方便地插入数据、创建索引、查看表结构等。它并非必需，但能极大提升开发效率。
• tabulate：一个轻量级的库，可以把列表数据漂亮地打印成表格，让终端输出的查询结果一目了然。

3.2 准备示例数据库与数据

为了演示，我们需要一个包含真实数据的SQLite数据库。让我们创建一个模拟的电商业务数据库。

# 文件：create_sample_db.py import sqlite3 import sqlite_utils # 连接到数据库（如果不存在则会创建） db = sqlite_utils.Database("ecommerce.db") # 删除已存在的表（如果之前运行过） db["users"].drop(ignore=True) db["products"].drop(ignore=True) db["orders"].drop(ignore=True) # 创建用户表 db["users"].create({ "id": int, "name": str, "email": str, "signup_date": str, # 为了简单，用文本存储日期 "country": str }, pk="id") # 设置id为主键 # 插入示例用户数据 db["users"].insert_all([ {"id": 1, "name": "张三", "email": "[e-mail]", "signup_date": "2024-01-15", "country": "中国"}, {"id": 2, "name": "李四", "email": "[e-mail]", "signup_date": "2024-02-20", "country": "美国"}, {"id": 3, "name": "王五", "email": "[e-mail]", "signup_date": "2024-03-10", "country": "中国"}, {"id": 4, "name": "赵六", "email": "[e-mail]", "signup_date": "2024-01-05", "country": "英国"}, ]) # 创建产品表 db["products"].create({ "id": int, "name": str, "category": str, "price": float, "stock_quantity": int }, pk="id") db["products"].insert_all([ {"id": 101, "name": "无线鼠标", "category": "电子产品", "price": 89.99, "stock_quantity": 150}, {"id": 102, "name": "机械键盘", "category": "电子产品", "price": 299.00, "stock_quantity": 80}, {"id": 103, "name": "马克杯", "category": "家居用品", "price": 25.50, "stock_quantity": 300}, {"id": 104, "name": "编程书籍", "category": "图书", "price": 59.80, "stock_quantity": 45}, ]) # 创建订单表（关联用户和产品） db["orders"].create({ "id": int, "user_id": int, # 外键，关联users.id "product_id": int, # 外键，关联products.id "quantity": int, "order_date": str, "status": str # 例如：'pending', 'shipped', 'delivered' }, pk="id", foreign_keys=[ ("user_id", "users", "id"), ("product_id", "products", "id") ]) db["orders"].insert_all([ {"id": 1001, "user_id": 1, "product_id": 101, "quantity": 1, "order_date": "2024-03-01", "status": "delivered"}, {"id": 1002, "user_id": 2, "product_id": 102, "quantity": 1, "order_date": "2024-03-05", "status": "shipped"}, {"id": 1003, "user_id": 1, "product_id": 103, "quantity": 2, "order_date": "2024-03-10", "status": "pending"}, {"id": 1004, "user_id": 3, "product_id": 101, "quantity": 1, "order_date": "2024-03-12", "status": "delivered"}, {"id": 1005, "user_id": 4, "product_id": 104, "quantity": 1, "order_date": "2024-02-28", "status": "delivered"}, ]) print("示例数据库 'ecommerce.db' 创建成功！") print("包含表：users, products, orders")

运行这个脚本：python create_sample_db.py。你会得到一个名为ecommerce.db的数据库文件，里面包含了用户、产品、订单三个表和一些模拟数据。这是我们后续所有查询的基础。

3.3 配置AI模型访问

这是最关键的一步，你需要获取访问Claude Code模型的凭证。由于Claude Code的具体部署方式可能多样（本地部署、通过特定平台API等），这里我以假设其提供类似OpenAI的API接口为例。

1. 获取API密钥：前往你所使用的AI模型服务平台（例如Anthropic的Console，或其他集成了Claude Code的服务商），创建一个账户并获取API Key。
2. 安全存储密钥：绝对不要将API Key硬编码在代码中。最佳实践是使用环境变量。

   # 在终端中设置环境变量（仅当前会话有效） export CLAUDE_API_KEY="your_actual_api_key_here"

   对于长期项目，可以将这行命令添加到你的shell配置文件（如~/.bashrc或~/.zshrc）中，或者使用.env文件配合python-dotenv库来管理。
3. 在代码中读取密钥：

   import os api_key = os.environ.get("CLAUDE_API_KEY") if not api_key: raise ValueError("请设置环境变量 CLAUDE_API_KEY")

实操心得：模型接入这一步最容易卡住。如果遇到连接问题，首先检查：1) API Key是否正确且未过期；2) 网络环境是否能访问该API端点（某些服务可能有区域限制）；3) 你安装的SDK版本是否与API兼容。可以先用一个最简单的文本生成请求测试连通性，再进入复杂的Text-to-SQL任务。

4. 核心引擎：提示词（Prompt）设计与优化

整个系统的智能程度，八成取决于提示词的设计。一个好的Prompt需要清晰、无歧义地告诉AI模型三件事：你的角色、任务背景、以及你期望它输出的格式。

4.1 基础Prompt模板构建

我们的任务背景是“根据数据库Schema和用户问题生成SQL”。一个最基础的Prompt模板可以这样设计：

你是一个专业的SQL专家。请根据以下数据库表结构信息，将用户的自然语言问题转换为准确、高效、语法正确的SQLite SQL查询语句。 ### 数据库表结构 (Schema): {数据库Schema信息} ### 用户问题: {用户输入的自然语言问题} ### 要求： 1. 只输出SQL语句，不要输出任何解释、说明或Markdown格式的代码块标记（如```sql）。 2. 确保SQL语句符合SQLite的语法规范。 3. 如果用户问题模糊或信息不足，基于常见的业务逻辑做出合理假设，并在生成的SQL中用注释说明你的假设（使用`--`注释）。 4. 只生成SELECT查询语句，不要生成INSERT、UPDATE、DELETE、DROP等可能修改数据或结构的语句。 ### SQL查询语句：

这个模板包含了几个关键部分：

• 角色定义：“你是一个专业的SQL专家”。这给模型设定了一个身份，引导它用专家的思维来解决问题。
• 上下文注入：{数据库Schema信息}是一个占位符，我们需要用程序动态地将真实的表结构填充进去。
• 具体任务：“将用户的自然语言问题转换为...SQLite SQL查询语句”。
• 输出格式指令：“只输出SQL语句”。这非常重要，能确保我们得到的响应是纯净的、可直接执行的代码，而不是一段包含解释的文本。
• 安全与规范限制：要求符合SQLite语法，并且只生成SELECT语句。这是防止模型生成危险操作（如删除表）的重要安全栅栏。
• 容错处理：对于模糊问题，允许模型做出合理假设并用注释说明。这提高了系统的鲁棒性。

4.2 动态获取并格式化Schema信息

我们不能把整个数据库的所有信息都一股脑塞给模型，那样会浪费Token（影响成本和速度），也可能干扰模型的判断。我们需要一个函数，能够根据用户问题（或默认）提取出相关的表结构，并以清晰的方式格式化。

一个简单的实现是，先提取所有表的基本信息，然后根据表名是否可能在问题中被提及（一个简单的关键词匹配）来决定是否包含其完整结构。更高级的做法可以引入向量数据库进行语义检索，但初期我们用简单方法即可。

# 文件：schema_extractor.py import sqlite3 import re def get_database_schema(db_path, hint_table_names=None): """ 获取数据库的Schema信息。 Args: db_path: SQLite数据库文件路径。 hint_table_names: 一个可选的表名列表，用于提示哪些表可能相关。如果为None，则获取所有表。 Returns: 格式化后的Schema字符串。 """ conn = sqlite3.connect(db_path) cursor = conn.cursor() # 获取所有表名 cursor.execute("SELECT name FROM sqlite_master WHERE type='table';") all_tables = [row[0] for row in cursor.fetchall()] # 确定需要获取Schema的表 tables_to_fetch = all_tables if hint_table_names: # 简单的模糊匹配：如果用户问题中的词是表名的子串（忽略大小写），则认为相关 tables_to_fetch = [t for t in all_tables if any(hint.lower() in t.lower() for hint in hint_table_names)] # 如果没匹配到，则退回所有表，避免因匹配失败导致Schema缺失 if not tables_to_fetch: tables_to_fetch = all_tables print(f"提示：未根据提示词'{hint_table_names}'匹配到特定表，将返回所有表结构。") schema_lines = [] for table in tables_to_fetch: # 获取表的创建语句（包含字段、类型、约束等完整信息） cursor.execute(f"SELECT sql FROM sqlite_master WHERE type='table' AND name='{table}';") create_sql = cursor.fetchone() if create_sql: schema_lines.append(f"-- 表名: {table}") schema_lines.append(create_sql[0]) # 直接使用CREATE TABLE语句，信息最全 else: # 如果是视图或其他类型 schema_lines.append(f"-- 对象: {table} (非表或视图)") # 可选：获取示例数据的前几行，帮助模型理解数据内容（谨慎使用，可能暴露敏感数据） # cursor.execute(f"SELECT * FROM {table} LIMIT 2;") # sample_data = cursor.fetchall() # if sample_data: # schema_lines.append(f"-- 示例数据 (前2行): {sample_data}") schema_lines.append("") # 空行分隔不同表 conn.close() return "\n".join(schema_lines) # 从用户问题中提取可能的关键词作为表名提示（非常简单的实现） def extract_table_hints(user_question): """ 从用户问题中提取可能涉及的表名关键词。 这是一个启发式方法，实际应用可能需要更复杂的NLP或预定义映射。 """ # 预定义的表名列表 known_tables = ["users", "products", "orders"] hints = [] for table in known_tables: if table.lower() in user_question.lower(): hints.append(table) return hints if hints else None if __name__ == "__main__": # 测试函数 schema = get_database_schema("ecommerce.db", hint_table_names=["users", "orders"]) print(schema)

这个get_database_schema函数会返回类似下面的字符串，它将被填充到我们的Prompt模板的{数据库Schema信息}部分：

-- 表名: users CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT, signup_date TEXT, country TEXT) -- 表名: orders CREATE TABLE orders (id INTEGER PRIMARY KEY, user_id INTEGER, product_id INTEGER, quantity INTEGER, order_date TEXT, status TEXT, FOREIGN KEY (user_id) REFERENCES users (id), FOREIGN KEY (product_id) REFERENCES products (id))

注意事项：直接使用CREATE TABLE语句作为Schema描述，信息最准确，包含了字段名、类型、主键、外键约束。这比单纯列出字段名对AI模型更有帮助。外键信息尤其重要，它直接告诉了模型表之间的关联关系，是生成正确JOIN语句的关键。

4.3 Prompt的组装与调用

现在，我们可以将上述模块组合起来，形成一个完整的查询生成函数。

# 文件：sql_generator.py import os import openai # 或 anthropic from schema_extractor import get_database_schema, extract_table_hints # 假设使用OpenAI兼容的API client = openai.OpenAI( api_key=os.environ.get("CLAUDE_API_KEY"), base_url="https://api.anthropic.com/v1", # 这里需要替换为Claude Code模型服务的实际API地址 ) def generate_sql_from_nl(db_path, user_question, model="claude-3-haiku-20240307"): # 模型名需替换为实际可用的Claude Code模型 """ 核心函数：根据自然语言问题生成SQL。 """ # 1. 提取表名提示 table_hints = extract_table_hints(user_question) # 2. 获取动态Schema schema_text = get_database_schema(db_path, hint_table_names=table_hints) # 3. 构建Prompt prompt_template = f""" 你是一个专业的SQL专家。请根据以下数据库表结构信息，将用户的自然语言问题转换为准确、高效、语法正确的SQLite SQL查询语句。 ### 数据库表结构 (Schema): {schema_text} ### 用户问题: {user_question} ### 要求： 1. 只输出SQL语句，不要输出任何解释、说明或Markdown格式的代码块标记（如```sql）。 2. 确保SQL语句符合SQLite的语法规范。 3. 如果用户问题模糊或信息不足，基于常见的业务逻辑做出合理假设，并在生成的SQL中用注释说明你的假设（使用`--`注释）。 4. 只生成SELECT查询语句，不要生成INSERT、UPDATE、DELETE、DROP等可能修改数据或结构的语句。 ### SQL查询语句： """ # 4. 调用AI模型 try: response = client.chat.completions.create( model=model, messages=[ {"role": "user", "content": prompt_template} ], temperature=0.1, # 温度设低，使输出更确定、更稳定 max_tokens=500 ) generated_sql = response.choices[0].message.content.strip() # 清理可能的残留标记 generated_sql = generated_sql.replace("```sql", "").replace("```", "").strip() return generated_sql except Exception as e: return f"生成SQL时出错: {e}" if __name__ == "__main__": # 测试 question = "列出所有中国用户的名字和他们的邮箱" sql = generate_sql_from_nl("ecommerce.db", question) print("用户问题:", question) print("生成的SQL:\n", sql)

运行这个测试，你可能会得到类似这样的SQL输出：

SELECT name, email FROM users WHERE country = '中国';

实操心得：temperature参数在这里设置为一个较低的值（如0.1或0.2）非常关键。Text-to-SQL是一个需要高确定性的任务，我们不希望模型在SELECT和字段名上“自由发挥”。低温度值能促使模型选择概率最高的输出，从而提高SQL语句的准确性和一致性。

5. 安全执行与结果展示

拿到AI生成的SQL语句后，我们不能直接信任并执行。必须经过一个安全校验和执行的环节。

5.1 SQL安全校验与执行

我们的核心安全原则是：这是一个查询助手，不是一个数据库管理工具。因此，我们必须严格限制只能执行SELECT查询。

# 文件：query_executor.py import sqlite3 import re from tabulate import tabulate def is_select_query(sql): """ 简单但有效地检查SQL语句是否仅为SELECT查询。 注意：这种方法并非绝对安全，但对于防止明显的误操作是有效的第一道防线。 更严格的方案可以使用SQL解析器。 """ # 去除首尾空白，转换为小写 sql_clean = sql.strip().lower() # 检查是否以'select'开头（允许前面有注释） # 使用正则匹配，忽略开头的空白和注释行 lines = sql_clean.split('\n') first_non_comment_line = '' for line in lines: line_stripped = line.strip() if line_stripped and not line_stripped.startswith('--'): first_non_comment_line = line_stripped break # 检查第一个非注释行是否以select开头 return first_non_comment_line.startswith('select') def execute_safe_query(db_path, sql): """ 安全地执行SQL查询。 """ if not is_select_query(sql): return None, "错误：只允许执行SELECT查询语句。" conn = None try: conn = sqlite3.connect(db_path) conn.row_factory = sqlite3.Row # 这样fetchall返回的是字典-like的Row对象 cursor = conn.cursor() cursor.execute(sql) results = cursor.fetchall() column_names = [description[0] for description in cursor.description] if cursor.description else [] return results, column_names except sqlite3.Error as e: return None, f"SQL执行错误: {e}" finally: if conn: conn.close() def pretty_print_results(results, column_names): """ 使用tabulate美化打印查询结果。 """ if results is None: print("无结果或执行出错。") return if not column_names: print("查询未返回列信息。") return # 将Row对象转换为字典列表，方便tabulate处理 data = [dict(row) for row in results] print(tabulate(data, headers=column_names, tablefmt="grid", showindex="always")) # 整合函数：生成并执行查询 def ask_database(db_path, question): print(f"\n[问题] {question}") from sql_generator import generate_sql_from_nl # 避免循环导入 sql = generate_sql_from_nl(db_path, question) print(f"[生成的SQL]\n{sql}") if sql.startswith("生成SQL时出错"): print(sql) return results, columns_or_error = execute_safe_query(db_path, sql) if isinstance(columns_or_error, str): # 返回的是错误信息 print(f"[执行结果] {columns_or_error}") else: print("[查询结果]") pretty_print_results(results, columns_or_error) if __name__ == "__main__": # 测试几个问题 questions = [ "列出所有中国用户的名字和他们的邮箱", "统计每种产品的总销售额（销售额 = 单价 * 购买数量）", "找出在2024年3月下单的所有用户，显示用户姓名和订单日期", "哪个国家的用户数量最多？", ] for q in questions: ask_database("ecommerce.db", q) print("\n" + "="*50 + "\n")

这个execute_safe_query函数做了两件事：

1. 安全检查：通过is_select_query函数，粗略但快速地判断SQL是否以SELECT开头。这能拦截掉绝大部分非查询语句。需要注意的是，正则匹配不是百分百安全（比如复杂的嵌套子查询开头有注释等情况），但对于内部工具或原型来说，这层防护加上“只读数据库连接”的实践，已经足够。对于生产环境，应考虑使用更严格的SQL解析库或数据库权限控制。
2. 执行与异常处理：使用try...except包裹执行过程，捕获SQL语法错误、字段不存在等运行时异常，并给出友好提示。

5.2 处理复杂查询与模型“幻觉”

随着问题变复杂，AI模型可能会出错。常见的错误包括：

• 表名或字段名拼写错误：特别是当Schema信息复杂时。
• 错误的JOIN逻辑：混淆了表之间的关系。
• 生成不存在的函数或语法：使用了SQLite不支持的特定数据库函数。
• “幻觉”出不存在的字段：用户问题中提到了“销售额”，模型可能会在SELECT子句中直接写sales_amount，但这个字段实际不存在，需要从price * quantity计算得出。

我们的Prompt中已经要求模型“基于常见的业务逻辑做出合理假设”，并在SQL中用注释说明。当执行出错时，我们可以将错误信息反馈给用户，甚至可以考虑设计一个“迭代修正”的机制：将错误信息和原始问题、Schema一起，再次发送给模型，要求它修正SQL。这构成了一个简单的自我纠错循环。

def generate_sql_with_feedback(db_path, user_question, previous_error=None): """ 带错误反馈的SQL生成。 """ table_hints = extract_table_hints(user_question) schema_text = get_database_schema(db_path, hint_table_names=table_hints) prompt = f""" 你是一个专业的SQL专家。请根据以下数据库表结构信息，将用户的自然语言问题转换为准确、高效、语法正确的SQLite SQL查询语句。 ### 数据库表结构 (Schema): {schema_text} ### 用户问题: {user_question} """ if previous_error: prompt += f""" ### 之前生成的SQL执行出错: 错误信息: {previous_error} 请分析错误原因，并重新生成正确的SQL语句。 """ prompt += """ ### 要求： 1. 只输出SQL语句，不要输出任何解释、说明或Markdown格式的代码块标记（如```sql）。 2. 确保SQL语句符合SQLite的语法规范。 3. 如果用户问题模糊或信息不足，基于常见的业务逻辑做出合理假设，并在生成的SQL中用注释说明你的假设（使用`--`注释）。 4. 只生成SELECT查询语句，不要生成INSERT、UPDATE、DELETE、DROP等可能修改数据或结构的语句。 ### SQL查询语句： """ # ... 调用模型 ...

6. 常见问题与排查技巧实录

在实际搭建和运行这个助手的过程中，我遇到了不少坑。这里把一些典型问题和解决方法记录下来，希望能帮你节省时间。

6.1 模型不按指令输出，附带额外解释

问题现象：生成的响应里除了SQL，还有“好的，根据您的问题，我生成了以下SQL...”这样的解释性文字。原因分析：Prompt的指令不够强硬，或者模型本身的“聊天”特性导致它倾向于输出完整的、带解释的回复。解决方案：

1. 强化指令：在Prompt中非常明确、反复强调“只输出SQL语句”。可以用加粗、换行等方式突出。
2. 调整消息角色：尝试将messages中的角色从user改为system来传递指令，或者组合使用system和user消息。例如：

   messages=[ {"role": "system", "content": "你是一个SQL生成器。你必须只输出SQL代码，不要有任何其他文本。"}, {"role": "user", "content": prompt_template} ]

3. 后处理清洗：像我们代码中做的那样，在拿到响应后，用字符串替换方法移除常见的标记如```sql和```。

6.2 生成的SQL语法正确，但查询结果为空或不对

问题现象：SQL能执行，不报错，但返回空结果或者结果与预期不符。原因分析：

1. 数据不匹配：用户问题中的条件（如“上个月”、“高价值用户”）与数据库中的实际数据不匹配。
2. 业务逻辑理解偏差：AI对“销售额”、“活跃用户”等业务术语的理解与你的定义不同。
3. Schema信息不足或过时：程序提取的Schema没有包含所有必要的表，或者数据库结构已变更。排查步骤：
4. 打印并审查生成的SQL：这是第一步。把AI生成的SQL复制出来，手动在数据库工具（如DB Browser for SQLite）里执行，看结果是否正确。
5. 检查Schema注入：打印出实际发送给模型的完整Prompt，确认Schema信息是否正确、完整。特别是外键关系，是否清晰传递给了模型。
6. 细化问题描述：用户的问题可能太模糊。尝试将问题拆解得更具体。例如，将“分析用户行为”改为“列出过去7天内登录次数大于5次的用户ID和最后登录时间”。
7. 提供数据示例：在Schema中，可以谨慎地加入一两行示例数据（如我们代码中注释掉的部分），帮助模型理解字段的实际内容和格式（例如，date字段是YYYY-MM-DD格式的文本还是时间戳）。注意数据脱敏。

6.3 处理模糊查询与边界情况

问题现象：用户问“最近的订单”，模型可能不知道“最近”是指时间上最近的一条，还是最近一周的所有订单。解决方案：这需要在Prompt设计时就加以引导。我们的Prompt中要求模型“做出合理假设并用注释说明”。一个更优的做法是，在最终面向用户的产品中，增加一个澄清交互的环节。当模型发现模糊点时，不是直接假设，而是生成一个追问，比如：“请问‘最近的订单’是指‘最新的一条订单’，还是‘过去7天内的所有订单’？”。这需要更复杂的对话状态管理，但能显著提升体验。

6.4 性能与成本考量

问题现象：随着数据库表增多、Schema变复杂，每次查询都提取全部Schema会导致Prompt过长，API调用成本增加、速度变慢。优化方案：

1. Schema缓存：数据库结构不会频繁变动。可以将Schema信息缓存到本地文件或内存中，定期（如每天）更新一次，而不是每次查询都去数据库读取。
2. 智能Schema筛选：实现更精准的Schema检索。可以用更高级的文本匹配（如TF-IDF）或嵌入向量（Embedding）相似度搜索，从所有表结构中找出与用户问题最相关的几个表，只把这些表的Schema注入Prompt。
3. 精简Schema描述：不一定非要完整的CREATE TABLE语句。可以自定义一种更紧凑的格式，例如：表名(字段1:类型, 字段2:类型, ...)，并保留关键约束说明。这需要在信息完整性和Token消耗之间取得平衡。

6.5 连接与API调用失败

问题现象：程序报错，提示API连接超时、认证失败或模型不可用。排查清单：

1. API Key：确认环境变量CLAUDE_API_KEY已正确设置且未过期。在终端执行echo $CLAUDE_API_KEY检查。
2. 网络代理：如果你的环境需要网络代理才能访问外部API，需要在代码中或系统环境里配置代理。对于openai库，可以这样设置：

   import os os.environ['HTTP_PROXY'] = 'http://your-proxy:port' os.environ['HTTPS_PROXY'] = 'http://your-proxy:port'

   重要安全提示：此处仅为说明技术配置方法。请务必使用合法合规的网络服务，并遵守相关法律法规。

3. 模型名称：确认model参数填写的是服务商提供的正确模型标识符。
4. 服务状态：查看AI模型服务商的状态页面，确认服务是否正常运行。
5. 额度与频次限制：检查账户是否有足够的额度或调用次数，是否触发了速率限制（Rate Limit）。可以在代码中加入简单的重试机制和延迟。

搭建这样一个自然语言查库助手，从零到一跑通核心流程，最大的收获不是最终生成的某一条SQL，而是理解了如何将一个模糊的用户需求，通过提示词工程、安全校验、异常处理等一系列环节，变成一个可靠、可用的工具。它本质上是一个“翻译器”和“执行器”的结合体。目前这个版本（上篇）已经具备了核心功能，你可以用它来快速查询预设的示例数据库。

但这只是起点。在实际业务中，数据库会更复杂，问题会更模糊，需求会更动态。在接下来的（下篇）里，我们可以探讨如何为这个助手“升级”，例如：引入Web界面让非技术人员也能用；连接真实的业务数据库；实现多轮对话，让助手能追问细节来澄清模糊需求；甚至让助手不仅能查数据，还能基于查询结果做一些简单的分析和图表建议。这些都将让这个工具从“玩具”走向“生产力”。