vanna文档编写：API文档、用户手册、开发指南

【免费下载链接】vanna 人工智能驱动的数据库查询 。使用RAG实现准确的文本到SQL的转换 。 项目地址: https://gitcode.com/GitHub_Trending/va/vanna

概述

Vanna是一个MIT许可的开源Python RAG（Retrieval-Augmented Generation，检索增强生成）框架，专门用于SQL生成和相关功能。它通过结合大语言模型（LLM）和向量数据库技术，实现从自然语言到SQL查询的智能转换。

核心架构

架构流程图

核心组件

组件类型	功能描述	实现类示例
LLM集成	负责与各种大语言模型交互	OpenAI_Chat, Anthropic_Chat, Gemini_Chat
向量数据库	存储和检索训练数据	ChromaDB_VectorStore, PgVector, Pinecone_Vector
数据库连接	连接各种SQL数据库执行查询	connect_to_snowflake, connect_to_postgres
核心逻辑	协调整个RAG流程	VannaBase 基类

快速开始

安装

pip install vanna

基础配置

# 使用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)

# 初始化Vanna实例
vn = MyVanna(config={
    'api_key': 'your-openai-api-key',
    'model': 'gpt-4'
})

API详细文档

核心方法

1. 训练方法

train() - 添加训练数据

# 训练DDL语句
vn.train(ddl="""
    CREATE TABLE customers (
        id INT PRIMARY KEY,
        name VARCHAR(100),
        email VARCHAR(150),
        created_at TIMESTAMP
    )
""")

# 训练业务文档
vn.train(documentation="客户表包含所有注册用户的基本信息")

# 训练SQL示例
vn.train(sql="SELECT name, email FROM customers WHERE created_at > '2024-01-01'")

2. 查询方法

ask() - 核心查询方法

result = vn.ask("查询2024年注册的客户数量")
# 返回: (SQL语句, DataFrame结果, Plotly图表, 后续问题列表)

generate_sql() - 仅生成SQL

sql = vn.generate_sql("显示销售额前10的客户")

3. 数据管理

get_training_data() - 获取所有训练数据

training_data = vn.get_training_data()

remove_training_data() - 删除训练数据

vn.remove_training_data("training-id-123")

数据库连接方法

Snowflake连接示例

vn.connect_to_snowflake(
    account="your-account",
    username="your-username",
    password="your-password",
    database="your-database",
    schema="your-schema"
)

PostgreSQL连接示例

vn.connect_to_postgres(
    host="localhost",
    dbname="mydatabase",
    user="myuser",
    password="mypassword",
    port=5432
)

支持的集成

LLM提供商支持

提供商	状态	配置文件
OpenAI	✅ 完全支持	openai_chat.py
Anthropic	✅ 完全支持	anthropic_chat.py
Google Gemini	✅ 完全支持	gemini_chat.py
HuggingFace	✅ 完全支持	hf.py
AWS Bedrock	✅ 完全支持	bedrock_converse.py
Ollama	✅ 完全支持	ollama.py
智谱AI	✅ 完全支持	ZhipuAI_Chat.py

向量数据库支持

数据库	状态	配置文件
ChromaDB	✅ 完全支持	chromadb_vector.py
pgvector	✅ 完全支持	pgvector.py
Pinecone	✅ 完全支持	pinecone_vector.py
FAISS	✅ 完全支持	faiss.py
Qdrant	✅ 完全支持	qdrant.py
Weaviate	✅ 完全支持	weaviate_vector.py
Milvus	✅ 完全支持	milvus_vector.py

SQL数据库支持

数据库	连接方法	状态
PostgreSQL	connect_to_postgres()	✅
MySQL	connect_to_mysql()	✅
Snowflake	connect_to_snowflake()	✅
BigQuery	connect_to_bigquery()	✅
SQLite	connect_to_sqlite()	✅
Oracle	connect_to_oracle()	✅
SQL Server	connect_to_mssql()	✅

高级用法

自定义LLM集成

from vanna.base.base import VannaBase
import your_custom_llm_library

class CustomLLMIntegration(VannaBase):
    def __init__(self, config=None):
        super().__init__(config)
        self.llm_client = your_custom_llm_library.Client(
            api_key=config.get('api_key')
        )
    
    def submit_prompt(self, prompt, **kwargs):
        # 实现自定义LLM调用逻辑
        response = self.llm_client.generate(prompt)
        return response
    
    def generate_embedding(self, data, **kwargs):
        # 实现自定义嵌入生成
        return self.llm_client.embed(data)

自定义向量存储

from vanna.base.base import VannaBase

class CustomVectorStore(VannaBase):
    def __init__(self, config=None):
        super().__init__(config)
        # 初始化自定义向量数据库连接
    
    def add_question_sql(self, question, sql, **kwargs):
        # 实现自定义存储逻辑
        embedding = self.generate_embedding(question)
        # 存储到自定义向量数据库
        return "storage-id"
    
    def get_similar_question_sql(self, question, **kwargs):
        # 实现自定义检索逻辑
        embedding = self.generate_embedding(question)
        # 从自定义向量数据库检索
        return similar_questions

最佳实践

训练数据组织

# 1. 先训练DDL结构
vn.train(ddl="CREATE TABLE orders (id INT, customer_id INT, amount DECIMAL)")

# 2. 添加业务文档
vn.train(documentation="订单表记录所有交易订单")

# 3. 添加示例查询
vn.train(sql="SELECT customer_id, SUM(amount) FROM orders GROUP BY customer_id")

# 4. 使用训练计划批量训练
plan = vn.get_training_plan_postgres()
vn.train(plan=plan)

错误处理和验证

try:
    result = vn.ask("复杂的业务查询")
    if result[1] is not None:  # 检查DataFrame结果
        print("查询成功")
        print(result[1].head())
except Exception as e:
    print(f"查询失败: {e}")
    # 可以在这里添加自动修复或重试逻辑

性能优化

提示词优化策略

# 自定义提示词模板
class OptimizedVanna(MyVanna):
    def get_sql_prompt(self, initial_prompt, question, question_sql_list, ddl_list, doc_list, **kwargs):
        # 优化提示词结构，减少token使用
        optimized_prompt = f"""
        你是一个SQL专家。基于以下上下文生成SQL查询：
        
        表结构:
        {self._format_ddl(ddl_list)}
        
        相关示例:
        {self._format_examples(question_sql_list)}
        
        业务上下文:
        {self._format_docs(doc_list)}
        
        请为这个问题生成SQL: {question}
        """
        return optimized_prompt

缓存策略

from functools import lru_cache

class CachedVanna(MyVanna):
    @lru_cache(maxsize=1000)
    def get_similar_question_sql(self, question, **kwargs):
        # 添加缓存以减少向量数据库查询
        return super().get_similar_question_sql(question, **kwargs)

故障排除

常见问题解决

问题	解决方案
SQL生成不准确	增加相关训练数据，特别是DDL和示例SQL
响应速度慢	优化提示词长度，启用缓存，使用更快的向量数据库
内存使用过高	分批处理训练数据，使用外部向量数据库
连接问题	检查网络连接和API密钥配置

调试模式

# 启用详细日志
vn.config['debug'] = True

# 或者自定义日志处理
class DebugVanna(MyVanna):
    def log(self, message, title="Info"):
        print(f"[DEBUG] {title}: {message}")
        # 可以添加到文件或监控系统

扩展开发

创建新的LLM集成

1. 继承基类: 从 VannaBase 继承
2. 实现抽象方法:
   • submit_prompt() - 处理LLM调用
   • generate_embedding() - 生成文本嵌入
3. 配置处理: 正确处理配置参数

创建新的向量存储

1. 实现向量存储接口:
   • add_question_sql(), get_similar_question_sql()
   • add_ddl(), get_related_ddl()
   • add_documentation(), get_related_documentation()
2. 处理嵌入向量: 确保正确的向量维度和对齐

版本兼容性

Python版本要求

• Python >= 3.9
• 建议使用Python 3.10+

主要依赖版本

# pyproject.toml 中的核心依赖
dependencies = [
    "requests", "tabulate", "plotly", "pandas", 
    "sqlparse", "kaleido", "flask", "flask-sock",
    "flasgger", "sqlalchemy"
]

安全考虑

数据隐私

• 数据库内容永远不会发送到LLM或向量数据库
• SQL执行在本地环境中进行
• 支持私有化部署所有组件

API安全

# 安全的API密钥管理
import os
api_key = os.environ.get('VANNA_API_KEY')
vn = MyVanna(config={'api_key': api_key})

社区和支持

获取帮助

• 查看详细文档：内置的help()函数和代码注释
• 社区讨论：GitHub Issues和Discord频道
• 商业支持：企业级部署和技术支持

贡献指南

1. Fork项目仓库
2. 创建特性分支
3. 提交更改并添加测试
4. 创建Pull Request

总结

Vanna提供了一个强大而灵活的框架，用于构建自然语言到SQL的转换系统。通过合理的架构设计和丰富的集成支持，它可以适应各种业务场景和技术栈。本文档涵盖了从基础使用到高级定制的各个方面，为开发者提供了全面的参考指南。

记住，成功的Vanna部署关键在于：

• 充足且高质量的训练数据
• 合适的LLM和向量数据库选择
• 持续的监控和优化
• 遵循安全最佳实践

【免费下载链接】vanna 人工智能驱动的数据库查询 。使用RAG实现准确的文本到SQL的转换 。 项目地址: https://gitcode.com/GitHub_Trending/va/vanna