# rag-example

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

## Basic Information

- **Project Name**: rag-example
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# rag-example

RAG（检索增强生成）学习示例项目，基于 uv workspace Monorepo 结构管理多个示例模块。

## 项目结构

```
rag-example/
├── AGENTS.md                     # 团队规范索引
├── openspec/agents/              # 完整规范体系
├── packages/
│   ├── pg-rag-example/           # PostgreSQL 向量数据库 RAG 示例
│   └── es-rag-example/           # Elasticsearch 向量数据库 RAG 示例
└── pyproject.toml                # workspace 定义 + 共享工具链配置
```

## 环境要求

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/) 包管理器

## 快速开始

```bash
# 安装所有子项目依赖
uv sync

# 运行测试
uv run pytest

# 代码检查
uv run ruff check
uv run mypy
```

## pg-rag-example 运行指南

### 前置准备

1. **PostgreSQL**：确保已安装 pgvector 扩展

   ```sql
   CREATE DATABASE rag_example;
   CREATE EXTENSION IF NOT EXISTS vector;
   ```

2. **BGE-M3 模型**：下载 [BGE-M3](https://huggingface.co/BAAI/bge-m3) 到本地目录，记录路径

3. **LLM 服务**：启动 OpenAI 兼容 API（如 [Ollama](https://ollama.com/)）

4. **配置环境变量**：

   ```bash
   cp packages/pg-rag-example/.env.example packages/pg-rag-example/.env
   # 编辑 .env 填入 PG 连接、MODEL_PATH、LLM 配置
   ```

### 运行示例

每个示例分两步：先建索引（index.py），再检索生成（search.py）。

```bash
# 01 — Dense Only：纯稠密向量 ANN 检索
uv run --directory packages/pg-rag-example python examples/01-dense-only/index.py
uv run --directory packages/pg-rag-example python examples/01-dense-only/search.py

# 02 — Hybrid Dense+Sparse：稠密 + 稀疏 RRF 融合检索
uv run --directory packages/pg-rag-example python examples/02-hybrid-dense-sparse/index.py
uv run --directory packages/pg-rag-example python examples/02-hybrid-dense-sparse/search.py

# 03 — Full ColBERT：混合检索 + ColBERT MaxSim 重排序
uv run --directory packages/pg-rag-example python examples/03-full-colbert/index.py
uv run --directory packages/pg-rag-example python examples/03-full-colbert/search.py
```