记录RAG代理
🚀 状态和质量
📦 项目信息
⭐ 社区
基于 Streamlit 的智能代理，可通过 PGVector 对存储在 PostgreSQL 中的知识库进行对话访问。使用 RAG（检索增强生成）搜索嵌入式文档，并通过引用来源提供上下文和准确的答案。支持多种文档格式。
🎓 新来Docling？
从教程开始！ 咨询海报 docling_basics/ 对于教授Docling基础知识的渐进式示例：
- 简单的PDF转换 基本文件处理
- 支持多种格式 -格式PDF、Word、PowerPoint
- 伊布里多 - RAG系统的智能切割
这些教程为了解这个完整的RAG代理是如何工作的基础。 转到 Docking Basics
功能
- 💬 与Streamlit交互式Web聊天界面
- 🔍 通过嵌入式矢量文档进行语义搜索
- 📚 使用 RAG 管道进行上下文感知响应
- 🎯 引用提供的所有信息的来源
- 🔄 在令牌到达时实时串流文本输出
- 💾 PostgreSQL/PGVector 用于可扩展的知识存储
- 🧠 在班次之间保持对话历史
先决条件
| 工具 | 版本 | 安装链接 |
|---|---|---|
| python | 3.10+ （推荐3.11） | python.org/下载 |
| 紫外线 | 0.9.13+ （推荐最新版本） | docs.astral.sh/uv |
| PostgreSQL | 16+带PGVector | postgresql.org |
| 码头工人 最新（可选） |
API密钥要求：
OPENAI_API_KEY-每个嵌入的OpenAI API密钥e LLM(在这里获取)
提供商数据库支持：
- PostgreSQL自托管架构PGVector
- Supabase（管理PostgreSQL）
- Neon（无服务器PostgreSQL）
快速开始
估计时间：~3-4分钟 （不包括安装先决条件）
1. 克隆并安装依赖关系（~30秒）
# Clona il repository
git clone https://github.com/stefanopiga/Agent-RAG.git
cd Agent-RAG
# Installa le dipendenze usando UV
uv sync2. 设置环境变量（~30秒）
cp .env.example .env修改 .env 您的凭据：
# RICHIESTO: Connessione database PostgreSQL con PGVector
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
# RICHIESTO: OpenAI API key
OPENAI_API_KEY=sk-...
# OPZIONALE: Modello LLM (default: gpt-4o-mini)
LLM_CHOICE=gpt-4o-mini
# OPZIONALE: Modello embedding (default: text-embedding-3-small)
EMBEDDING_MODEL=text-embedding-3-small
# OPZIONALE: LangFuse per observability/tracing (MCP server)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com每个提供程序的 DATABASE_URL 示例：
- 自托管:
postgresql://user:password@localhost:5432/dbname - Supabase:
postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres - 霓虹:
postgresql://[user]:[password]@[endpoint].neon.tech/[dbname]
3. 设置数据库（~1分钟）
新安装：
# Esegui lo schema completo (include HNSW index ottimizzato)
# Per Supabase: Usa SQL Editor e incolla contenuto di optimize_index.sql
psql $DATABASE_URL str:
"""Cerca nella knowledge base usando similarità semantica.
Args:
query: Query di ricerca
limit: Numero massimo risultati
source_filter: Filtro opzionale (es: "docling", "langfuse-docs")
"""
# Genera embedding per la query
# Cerca in PostgreSQL con PGVector
# Applica filtro fonte se specificato
# Formatta e restituisce i risultati架构数据库
documents存储带元数据的原始文档
- id, title, source, content, metadata, created_at, updated_at
chunks存储带有矢量嵌入的文本片段
- id, document_id, content, embedding （向量（1536））， chunk_index, metadata, token_count
match_chunks()PostgreSQL 函数用于向量相似性搜索
- 使用共弦相似性（1 - (embedding query_embedding)) - 返回相似度分数高于门槛的片段
🚀 每个游标IDE的MCP服务器
该项目包括一个 模型上下文协议（MCP）服务器 与 Cursor IDE 集成。
设置MCP：
- 运行命令启动mcp服务器：
# avvia il server mcp
uv run python mcp_server.py
# apri la porta locale http://localhost:8080/health
curl http://localhost:8080/health
- 配置
.cursor/mcp.json:
{
"mcpServers": {
"docling-rag": {
"command": "uv",
"args": [
"run",
"--project",
"/path/to/docling-rag-agent",
"python",
"/path/to/docling-rag-agent/mcp_server.py"
]
}
}
}- 重新启动游标 MCP服务器自动启动
- 使用工具 在光标中：
Chiedi: "What is Docling?"
Il MCP tool cercherà nella knowledge base e risponderà con context性能MCP：
- ✅ 全局嵌入器实例：-70%延迟（消除300-500ms的开销）
- ✅ HNSW指数：-61%查询时间（平均1395ms，缓存237ms）
- ✅ 优化的连接池： -20%的开销
- ✅ 每次监测的定时仪器
完整文档：
docs/performance-optimization-guide.md- 详细技术指南docs/optimization-summary.md- 结果分析docs/optimization-deployment.md-部署指南
🤖 代码质量和CI/CD
CodeRabbit集成
repository 使用 CodeRabbit 对每个提取请求进行AI驱动的自动代码审查。
功能：
- ✅ 自动审查每个PR
- 📝 最佳实践建议
- 🔒 安全分析自动化
- 📊 高级别修改摘要
CI/CD管道
GitHub Actions 在每个 PR 上自动运行，并推送到 main/develop:
| Job | Descrizione | Tool |
|---|---|---|
| 棉绒 | 棉绒格式检查 | Ruff |
| 类型检查 | 类型检查统计 | Mypy |
| 测试 | 单元/集成测试覆盖率>70% | Pytest |
| 构建 | Docker镜像构建验证（\ query_embedding |
## 部署Docker
### Docker的先决条件
- Docker桌面24.0+([下载](https://www.docker.com/products/docker-desktop/))
- Docker Compose v2.0+（包括Docker桌面版）
### 快速启动Docker（约2分钟）
**启动完整的应用程序：**
Avvia tutti i servizi
docker-compose up --build -d
Visualizza i log
docker-compose logs -f rag-agent
该应用程序将可在 `http://localhost:8501`
**使用 Docker 输入文件：**
Default: CANCELLA il DB e reingerisce tutto (raccomandato)
docker-compose --profile ingestion up ingestion
AGGIUNGERE documenti senza cancellare (può creare duplicati)
Usa il doppio slash per Windows + Git Bash
docker-compose run --rm ingestion uv run python -m ingestion.ingest --documents //app/documents --no-clean
Con opzioni personalizzate
docker-compose run --rm ingestion uv run python -m ingestion.ingest \ --documents /app/documents \ --chunk-size 800 \ --verbose
**⚠️ 注：** default 命令 **自动删除** 摄入前的所有现有数据，以避免重复。美国 `--no-clean` 只有当您想要添加新文档而不触摸现有文档时。
**有用的命令 ：**
Ferma tutti i servizi
docker-compose down
Ricostruisci le immagini dopo modifiche al codice
docker-compose build
Visualizza i container attivi
docker-compose ps
Accedi al container per debugging
docker-compose exec rag-agent bash
## 故障排除
### 常见问题
问题 | 原因 | 解决方案 |
| ------------------------------ | -------------------------- | -------------------------------------------------------------------------------- |
| `connection refused` | 数据库无法访问 | 检查 `DATABASE_URL` PostgreSQL是活跃的。
| `extension "vector" not found` | PGVector 未安装 | 运行 `CREATE EXTENSION vector;` 使用 Docker 映像 `pgvector/pgvector:pg16` |
| `OPENAI_API_KEY not set` | 缺少变量 | 添加 `OPENAI_API_KEY` 在文件中 `.env` |
| `uv: command not found` | UV 未安装 | 安装： `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| `Python version mismatch` | Python \ str:
"""
Cerca nella knowledge base usando similarità semantica.
Args:
query: La query di ricerca per trovare informazioni rilevanti
limit: Numero massimo di risultati da restituire (default: 5)
source_filter: Filtro opzionale per cercare solo in fonti specifiche
Esempi: "docling", "langfuse-docs", "langfuse-docs/deployment"
Se fornito, verranno cercati solo documenti il cui percorso
sorgente contiene questa stringa
Returns:
Risultati di ricerca formattati con citazioni delle fonti
"""使用过滤器的例子：
# Cerca in tutta la knowledge base
await search_knowledge_base(query="come fare il deploy")
# Cerca solo nella documentazione Docling
await search_knowledge_base(
query="come fare il deploy",
source_filter="docling"
)
# Cerca solo nella sezione deployment di Langfuse
await search_knowledge_base(
query="deployment cloud",
source_filter="langfuse-docs/deployment"
)过滤器是如何工作的：
- 代理在用户指定源时自动识别
- 使用 pattern matching case-insensitive 应用过滤器
- 用于分离不同的文档（Docking，Langfuse等）
- 防止反应中的跨文档污染
数据库函数
-- Ricerca similarità vettoriale
SELECT * FROM match_chunks(
query_embedding::vector(1536),
match_count INT,
similarity_threshold FLOAT DEFAULT 0.7
)返回 chunk ：
id：UUID数据块content： 文本内容embedding: 矢量嵌入similarity共弦相似度评分（0-1）document_title： 源文件标题document_source： 源文件路径
📚 文档
完整的项目文档，包括API参考，可在 guide/.
本地视图
您可以启动本地服务器以浏览文档：
# Avvia il server di documentazione
uv run mkdocs serve文件将可在 http://127.0.0.1:8000.
静态生成
要生成静态文档 （HTML）：
# Genera la documentazione in site/
uv run mkdocs buildGitHub页面
文档在每次推送到分支时都会自动发布到 GitHub Pages main.
项目结构
docling-rag-agent/
├── app.py # Interfaccia web Streamlit
├── docling_mcp/ # MCP server per Cursor IDE (standalone)
├── core/
│ ├── agent.py # PydanticAI agent wrapper
│ └── rag_service.py # Core RAG logic (decoupled)
├── ingestion/
│ ├── ingest.py # Pipeline ingestione documenti
│ ├── embedder.py # Generazione embedding con caching
│ └── chunker.py # Chunking intelligente (Docling HybridChunker)
├── utils/
│ ├── providers.py # Configurazione modelli/client OpenAI
│ ├── db_utils.py # Connection pooling ottimizzato
│ └── models.py # Modelli Pydantic per validazione
├── sql/
│ └── optimize_index.sql # Schema completo + HNSW index ottimizzato
├── scripts/
│ ├── optimize_database.py # Tool gestione index e performance
│ └── test_mcp_performance.py # Performance test suite
├── docs/
│ ├── optimization-summary.md # Analisi performance optimization
│ ├── performance-optimization-guide.md
│ └── optimization-deployment.md
├── documents/ # Documenti per ingestione
├── pyproject.toml # Dipendenze progetto (uv)
├── .env.example # Template variabili d'ambiente
└── README.md # Questo file