# vanna_ollama_project_v2

**Repository Path**: ning_wen_jie/vanna_ollama_project_v2

## Basic Information

- **Project Name**: vanna_ollama_project_v2
- **Description**: text2sql
demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-04-03
- **Last Updated**: 2025-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vanna.ai + DeepSeek 自然语言SQL查询系统

这是一个基于 Vanna.ai 和 DeepSeek API 的自然语言到SQL转换系统。它使用 ChromaDB 作为向量数据库，SQLite 作为关系数据库。

## 功能特点

- 支持自然语言到SQL的转换
- 使用 DeepSeek API 进行语言理解和SQL生成
- 使用 ChromaDB 存储表结构的向量表示
- 支持CSV文件上传和数据管理
- 提供友好的Web界面

## 安装要求

- Python 3.8+
- 依赖包：见 requirements.txt

## 快速开始

1. 克隆仓库：
```bash
git clone https://gitee.com/ning_wen_jie/vanna_ollama_project_v2.git
cd vanna_ollama_project_v2
```

2. 安装依赖：
```bash
pip install -r requirements.txt
```

3. 配置 DeepSeek API：
   - 在运行程序之前，需要设置您的 DeepSeek API 密钥
   - 在 `create_vanna_instance()` 调用时传入您的 API 密钥

4. 运行应用：
```bash
python app.py
```

## 使用说明

1. 上传数据：
   - 在"上传CSV数据"标签页上传CSV文件
   - 系统会自动创建数据表并存储数据

2. 查询数据：
   - 切换到"自然语言查询"标签页
   - 输入自然语言问题
   - 系统会自动生成并执行SQL查询

## 配置说明

本项目使用外部配置文件来存储敏感信息，如API密钥。按照以下步骤设置配置：

1. 复制示例配置文件：
   ```
   cp config.example.py config.py
   ```

2. 在 `config.py` 中填入您的DeepSeek API密钥和其他配置：
   ```python
   DEEPSEEK_API_KEY = "您的DeepSeek API密钥"
   ```

3. `config.py` 文件已在 `.gitignore` 中配置为不提交到Git，确保您的敏感信息安全。

- DeepSeek API 配置：
  - API 密钥：在创建实例时传入
  - 基础URL：默认为 "https://api.deepseek.com"

- 数据库配置：
  - SQLite数据库：默认使用 ./database.db
  - ChromaDB：默认使用 ./chroma_db 目录

## 注意事项

- 请确保在使用前设置正确的 DeepSeek API 密钥
- 建议将敏感配置信息（如API密钥）存储在环境变量中
- 上传CSV文件时，请确保文件编码为UTF-8或GBK

## 更新日志

### v2.0.0
- 从 Ollama 迁移到 DeepSeek API
- 改进了表结构处理
- 优化了SQL生成逻辑
- 添加了更多错误处理

## 许可证

MIT License

## 项目结构

- `app.py`: 主应用入口，包含Gradio前端界面
- `vanna_integration.py`: Vanna.ai与Ollama和ChromaDB的集成
- `sqlite_handler.py`: SQLite数据库处理器
- `csv_uploader.py`: CSV上传功能实现
- `requirements.txt`: 项目依赖列表
- `uploads/`: CSV文件上传目录
- `database.db`: SQLite数据库文件
- `chroma_db/`: ChromaDB数据存储目录

## 注意事项

- 本应用需要Ollama服务在本地运行，默认地址为http://localhost:11434
- 如果Ollama服务运行在其他地址，请修改`app.py`中的`ollama_url`参数
- 默认使用llama3模型，可以根据需要修改为其他Ollama支持的模型
- 首次查询可能需要一些时间，因为需要加载模型和处理数据
- 查询结果的质量取决于LLM模型的能力和训练数据的质量
- 在Windows环境中安装numpy可能会遇到兼容性问题，建议使用预编译的二进制包：
  ```
  pip install --only-binary=numpy numpy==1.24.3
  ```

## 与官方文档的一致性

本项目严格按照[Vanna.ai官方文档](https://vanna.ai/docs/sqlite-ollama-chromadb/)实现，使用了官方推荐的方式集成Ollama和ChromaDB，确保了最佳的兼容性和性能。

## 自定义配置

如果需要修改默认配置，可以编辑`app.py`文件中的以下参数：

- `DB_PATH`: SQLite数据库文件路径
- `UPLOAD_DIR`: CSV文件上传目录
- `CHROMA_PATH`: ChromaDB数据存储目录
- `ollama_model`: Ollama模型名称
- `ollama_url`: Ollama服务地址

## 贡献

欢迎提交问题和改进建议！