# rag-examples

**Repository Path**: bytesifter/rag-examples

## Basic Information

- **Project Name**: rag-examples
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文本向量化检索系统

基于 Milvus 的命令行文本向量化检索工具，提供语义级别的文本搜索能力。

## 核心功能

- **文本索引**：读取 TXT 文件，自动分块、向量化、存入 Milvus
- **语义搜索**：基于向量相似度检索，支持同义词、近义词匹配
- **重复处理**：同一文件重复索引时自动覆盖旧版本
- **本地模型**：使用 BGE-Large-ZH-v1.5，无需 API 密钥

## 快速开始

### 前置条件

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) 包管理器
- Milvus 向量数据库（192.168.56.120:3006）
- BGE-Large-ZH-v1.5 模型（本地下载）

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd rag-examples

# 安装依赖
uv sync
```

### 下载模型

```bash
# 使用 uv run huggingface-cli（推荐）
uv run huggingface-cli download BAAI/bge-large-zh-v1.5 --local-dir models/bge-large-zh-v1.5

# 或使用 git clone
cd models
git clone https://huggingface.co/BAAI/bge-large-zh-v1.5
```

### 配置

```bash
# 复制配置模板
cp .env.example .env

# 编辑配置文件
# 必须配置 EMBEDDING_MODEL_PATH
```

`.env` 配置项：

```bash
# Milvus 配置
MILVUS_HOST=192.168.56.120
MILVUS_PORT=3006
MILVUS_COLLECTION_NAME=rag_documents

# Embedding 模型配置（必填）
EMBEDDING_MODEL_NAME=bge-large-zh-v1.5
EMBEDDING_MODEL_PATH=models/bge-large-zh-v1.5

# 分块配置
CHUNK_SIZE=512
CHUNK_OVERLAP=50

# 搜索配置
SEARCH_TOP_K=1
SEARCH_THRESHOLD=0.0
```

### 使用

**索引文件：**

```bash
# 基本用法
uv run python -m examples.milvus_rag.index_file path/to/file.txt

# 自定义分块大小
uv run python -m examples.milvus_rag.index_file file.txt -c 1024 -o 100
```

**搜索：**

```bash
# 基本用法
uv run python -m examples.milvus_rag.search "什么是人工智能？"

# 返回多条结果
uv run python -m examples.milvus_rag.search "查询文本" -k 5 -t 0.7
```

## 项目结构

```
rag-examples/
├── docs/                    # 文档
│   ├── PRD/v1.0.0.md       # 产品需求文档
│   ├── AD/v1.0.0.md        # 应用设计书
│   └── TSD/v1.0.0.md       # 技术方案
├── src/
│   └── milvus_rag/         # 核心模块
│       ├── config.py       # 配置管理
│       ├── embeddings.py   # Embedding 组件
│       ├── chunker.py      # 分块组件
│       ├── milvus_client.py # Milvus 客户端
│       ├── indexer.py      # 索引服务
│       └── searcher.py     # 搜索服务
├── examples/
│   └── milvus_rag/         # 命令行入口
│       ├── index_file.py   # 索引命令
│       └── search.py       # 搜索命令
├── tests/                   # 单元测试
├── models/                  # 模型目录（不提交）
├── .env                     # 配置文件（不提交）
├── .env.example             # 配置模板
└── pyproject.toml           # 项目配置
```

## 文档

| 文档 | 说明 |
|------|------|
| [PRD](docs/PRD/v1.0.0.md) | 产品需求文档 - 功能需求、业务流程 |
| [AD](docs/AD/v1.0.0.md) | 应用设计书 - 应用架构、模块划分 |
| [TSD](docs/TSD/v1.0.0.md) | 技术方案 - 技术选型、代码设计 |

## 开发

### 代码质量

```bash
# 格式化
uv run ruff format .

# 检查
uv run ruff check .

# 类型检查
uv run mypy src/ examples/
```

### 测试

```bash
# 运行所有测试
uv run pytest

# 运行指定测试
uv run pytest tests/test_milvus_rag.py -v
```

### 包管理

```bash
# 添加依赖
uv add <package>

# 同步环境
uv sync

# 运行命令
uv run python <script>
```

## 安全须知

- **不提交 `.env` 文件**：包含配置信息，已在 `.gitignore` 中
- **不提交 `models/` 目录**：模型文件较大，已在 `.gitignore` 中
- **本地模型**：无需 API 密钥，数据不出本地

## 许可证

MIT License