Agent Rag

记录RAG代理

🚀 状态和质量

 

📦 项目信息

](https://github.com/stefanopiga/Agent-RAG/releases)  

⭐ 社区

   

基于 Streamlit 的智能代理，可通过 PGVector 对存储在 PostgreSQL 中的知识库进行对话访问。使用 RAG（检索增强生成）搜索嵌入式文档，并通过引用来源提供上下文和准确的答案。支持多种文档格式。

🎓 新来Docling？

从教程开始！ 咨询海报 docling_basics/ 对于教授Docling基础知识的渐进式示例：

1. 简单的PDF转换 基本文件处理
2. 支持多种格式 -格式PDF、Word、PowerPoint
3. 伊布里多 - RAG系统的智能切割

这些教程为了解这个完整的RAG代理是如何工作的基础。 转到 Docking Basics

功能

• 💬 与Streamlit交互式Web聊天界面
• 🔍 通过嵌入式矢量文档进行语义搜索
• 📚 使用 RAG 管道进行上下文感知响应
• 🎯 引用提供的所有信息的来源
• 🔄 在令牌到达时实时串流文本输出
• 💾 PostgreSQL/PGVector 用于可扩展的知识存储
• 🧠 在班次之间保持对话历史

先决条件

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 sync

2. 设置环境变量（~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：

1. 运行命令启动mcp服务器：

# avvia il server mcp
uv run python mcp_server.py

# apri la porta locale http://localhost:8080/health
curl http://localhost:8080/health

1. 配置 .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"
      ]
    }
  }
}

1. 重新启动游标 MCP服务器自动启动

1. 使用工具 在光标中：

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:

## 部署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 build

GitHub页面

文档在每次推送到分支时都会自动发布到 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