Vanna 的工作原理

Vanna 的核心是一个 Python 软件包，它使用检索增强来帮助您使用 LLM 为数据库生成准确的 SQL 查询。

Vanna 通过两个简单的步骤工作 - 在您的数据上训练 RAG“模型”，然后提出问题，这些问题将返回 SQL 查询，这些查询可以设置为在您的数据库上自动运行。

1. 在您的数据上训练 RAG“模型”。
2. 提出问题。

如果您不知道 RAG 是什么，请不要担心 - 您无需知道它在后台是如何工作的即可使用它。你只需要知道你 “训练” 了一个模型，该模型存储了一些元数据，然后用它来 “提出” 问题。

安装

pip install vanna

有许多可选软件包可以安装，因此请参阅文档了解更多详细信息。

进口

如果要自定义 LLM 或向量数据库，请参阅文档。

# The import statement will vary depending on your LLM and vector database. This is an example for OpenAI + ChromaDB

from vanna.openai.openai_chat import OpenAI_Chat
from vanna.chromadb.chromadb_vector import ChromaDB_VectorStore

class MyVanna(ChromaDB_VectorStore, OpenAI_Chat):
    def __init__(self, config=None):
        ChromaDB_VectorStore.__init__(self, config=config)
        OpenAI_Chat.__init__(self, config=config)

vn = MyVanna(config={'api_key': 'sk-...', 'model': 'gpt-4-...'})

# See the documentation for other options

训练

根据您的使用案例，您可能需要也可能不需要运行这些命令。有关更多详细信息，请参阅文档。vn.train

显示这些语句是为了让您了解其工作原理。

使用 DDL 语句进行训练

DDL 语句包含有关数据库中的表名、列、数据类型和关系的信息。

vn.train(ddl="""
    CREATE TABLE IF NOT EXISTS my-table (
        id INT PRIMARY KEY,
        name VARCHAR(100),
        age INT
    )
""")

使用文档进行训练

有时，您可能希望添加有关您的业务术语或定义的文档。

vn.train(documentation="Our business defines XYZ as ...")

使用 SQL 进行训练

您还可以将 SQL 查询添加到训练数据中。如果您已经有一些查询，这将非常有用。您只需从编辑器中复制并粘贴这些内容即可开始生成新的 SQL。

vn.train(sql="SELECT name, age FROM my-table WHERE name = 'John Doe'")

提问

vn.ask("What are the top 10 customers by sales?")

您将获得 SQL

SELECT c.c_name as customer_name,
        sum(l.l_extendedprice * (1 - l.l_discount)) as total_sales
FROM   snowflake_sample_data.tpch_sf1.lineitem l join snowflake_sample_data.tpch_sf1.orders o
        ON l.l_orderkey = o.o_orderkey join snowflake_sample_data.tpch_sf1.customer c
        ON o.o_custkey = c.c_custkey
GROUP BY customer_name
ORDER BY total_sales desc limit 10;

如果您已连接到数据库，您将获得以下表：

您还将获得一个自动的 Plotly 图表：

RAG 与 Fine-Tuning

抹布

• 可跨 LLM 移植
• 如果训练数据中的任何一个过时，则易于删除
• 运行成本比微调便宜得多
• 更面向未来 -- 如果出现更好的 LLM，您可以将其换掉

微调

• 如果您需要最小化提示符中的令牌，则很好
• 起步缓慢
• 训练和运行成本高昂（通常）

为什么选择 Vanna？

1. 复杂数据集的准确率高。Vanna 的功能与您提供的训练数据相关联更多的训练数据意味着大型复杂数据集的准确性更高
2. 安全且私密。您的数据库内容永远不会发送到 LLM 或向量数据库SQL 执行在本地环境中进行
3. 自我学习。如果通过 Jupyter 使用，您可以选择在成功执行的查询上对其进行“自动训练”如果通过其他接口使用，您可以让接口提示用户提供有关结果的反馈将正确的问题存储到 SQL 对以供将来参考，并使将来的结果更加准确
4. 支持任何 SQL 数据库。该软件包允许您连接到任何 SQL 数据库，否则您可以使用 Python 连接到这些数据库
5. 选择您的前端。大多数人从 Jupyter Notebook 开始。通过 Slackbot、Web 应用程序、Streamlit 应用程序或自定义前端向最终用户公开。

一、环境准备

1. Python环境配置

推荐使用Python 3.9+（低于3.7可能报错），

通过Anaconda管理虚拟环境：

conda create -n vanna python=3.9 conda activate vanna

2. 安装核心依赖：

pip install vanna[chromadb,mysql] # 根据数据库类型选择驱动（如psycopg2-binary、pymysql） pip install ipykernel # 可选，用于Jupyter调试

3. 向量数据库与LLM选择

向量数据库：默认支持ChromaDB（本地存储），可选Qdrant（需Docker部署）

docker pull qdrant/qdrant docker run -p 6333:6333 -v ./qdrant_storage:/qdrant/storage qdrant/qdrant

LLM模型：支持本地模型（如Ollama）或API模型（如Deepseek、Qwen）

二、初始化Vanna实例

1. 连接数据库

以MySQL为例，配置连接参数：

python

复制

from vanna.local import LocalContext_OpenAI vn = LocalContext_OpenAI(config={'api_key': 'sk-xxx'}) # 本地模式可忽略API密钥 vn.connect_to_mysql( host="127.0.0.1", user="root", password="123456", dbname="your_database", port=3306 )

2. 自定义模型与向量库

若需整合Qdrant和Ollama：

python

复制

from vanna.ollama import Ollama from vanna.qdrant import Qdrant_VectorStore class MyVanna(Qdrant_VectorStore, Ollama): def __init__(self, config=None): Qdrant_VectorStore.__init__(self, config=config) Ollama.__init__(self, config=config) vn = MyVanna(config={'url': 'http://localhost:6333', 'model': 'qwen:7b'})

三、模型训练

1. 训练数据类型

DDL语句：导入表结构定义（核心）：

python

复制

vn.train(ddl="CREATE TABLE employees (id INT PRIMARY KEY, name VARCHAR(100))")

2. 业务文档：补充语义信息（如字段中文注释）：

python

复制

vn.train(documentation="部门表包含员工ID、姓名和所属部门字段")

3. 历史SQL示例：提升生成准确性：

python

复制

vn.train(sql="SELECT name FROM employees WHERE department = '技术部'")

4. 批量训练技巧

自动提取元数据：

python

复制

df_schema = vn.run_sql("SELECT * FROM INFORMATION_SCHEMA.COLUMNS") plan = vn.get_training_plan_generic(df_schema) vn.train(plan=plan)

四、验证与优化

1. 生成SQL测试

python

复制

question = "统计技术部的员工人数" sql = vn.generate_sql(question) # 输出示例：SELECT COUNT(*) FROM employees WHERE department='技术部' result = vn.run_sql(sql)

2. 前端集成
   使用Flask快速搭建Web界面：

python

复制

from vanna.flask import VannaFlaskApp app = VannaFlaskApp(vn, allow_llm_to_see_data=True, chart=True) app.run(port=8084) # 访问http://localhost:8084

3. 优化策略

反馈学习：用户确认正确SQL后自动存入训练库。

4. 日志调试：启用vn.log = True查看生成逻辑。
5. 提示词调整：通过vn.train(prompts=...)优化LLM输出格式。

五、扩展配置

1. 多数据库支持

PostgreSQL/Snowflake：替换connect_to_postgres()或connect_to_snowflake()。

自定义数据库：实现run_sql方法返回Pandas DataFrame。

2. 模型本地化

下载向量模型（如all-MiniLM-L6-v2）：

python

复制

from modelscope import snapshot_download model_dir = snapshot_download('wengad/all-MiniLM-L6-v2')

模型路径配置至
~/.cache/chroma/onnx_models/。

六、常见问题

1. 依赖冲突：优先使用虚拟环境，安装失败时尝试pip install --no-deps。
2. 训练数据不足：至少需5-10条DDL或SQL示例覆盖核心业务表。
3. LLM效果差：避免量化模型（如Deepseek-7B），优先选择API模型或全参数量化版本。