内容
# Atlas — 智能代理 RAG 平台
> 导入知识库，然后询问智能代理，它通过 **混合搜索 + 重排序 + 知识图谱** 获取信息，通过 **MCP 调用工具** 进行推理，通过 **Claude / OpenAI / 本地模型** 路由，并被 **防护措施** （防止提示词注入、个人敏感信息脱敏）所保护，同时通过一流的 **评估框架** 进行衡量 —— 具备 **Langfuse** 可观测性、**Redis** 语义缓存和完整的 **Docker / Kubernetes / CI-CD** 支持。
<p align="center">
<img src="docs/demo.svg" alt="Atlas 在终端中回答问题并提供来源" width="820">
</p>
<p align="center">
<b>20 秒了解整个系统 — 无需密钥，无需服务：</b><br>
<code>pip install pydantic pydantic-settings fastapi "uvicorn[standard]" httpx rich && python -m atlas.cli demo</code>
</p>
Atlas 是一个单一的、完整的智能代理 RAG 系统，而不是一组演示示例。它的子系统通过 Python `Protocol` 接口解耦，因此每个托管依赖项都有一个轻量级的本地备用方案：**默认配置在无 API 密钥和外部服务的情况下完全离线运行**（内存向量存储、确定性嵌入器和模拟模型），每个托管集成（如 Claude、OpenAI、pgvector、Qdrant、Langfuse、Redis）都会在配置其密钥或 DSN 时自动激活。
---
## 架构
```mermaid
flowchart LR
subgraph Ingest["atlas.ingestion"]
SRC[文档 / URL / PDF] --> ETL[ETL + 清洁]
ETL --> CHUNK[分块]
CHUNK --> EMB[嵌入]
EMB --> VS[(向量存储)]
CHUNK --> KG[实体/关系提取] --> GRAPH[(知识图谱)]
GOWORKER[Go ingestion worker] -. 高吞吐量获取 .-> ETL
end
subgraph Retrieve["atlas.retrieval"]
Q[查询] --> HS[混合搜索：向量 + BM25]
VS --> HS
GRAPH --> GR[图检索]
HS --> RRF[互惠排名融合]
GR --> RRF
RRF --> RERANK[跨编码器重排序]
end
subgraph Agent["atlas.agent (LangGraph)"]
RERANK --> PLAN[计划 / 路由]
PLAN --> ROUTER{模型路由器}
ROUTER -->|合成| CLAUDE[Claude]
ROUTER -->|廉价分诊| GPT[OpenAI]
ROUTER -->|本地/私有| OLLAMA[Ollama / vLLM]
PLAN --> MCP[[MCP 工具服务器]]
end
subgraph Safety["atlas.guardrails"]
GIN[注入 + 个人敏感信息] --> Agent
Agent --> GOUT[个人敏感信息 + 内容过滤器]
end
U[用户] --> API[FastAPI + Next.js UI]
API --> GIN
GOUT --> API
Agent --> OBS[(Langfuse 跟踪)]
Agent --> CACHE[(Redis 语义缓存)]
Agent --> EVAL[atlas.evals: LLM 评估 + A/B 测试]
```
查看 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 以了解请求生命周期和设计深入解析。
---
## 功能
**检索**
- 混合搜索（稠密向量 + BM25 关键词）与互惠排名融合
- 知识图谱层：实体/关系在导入时提取，为多跳图检索器提供支持，该检索器的命中结果与 RRF 融合作为第三个 `graph_weight` 排名
- 融合候选者的跨编码器重排序
- 可插拔的向量存储，支持 `VectorStore` 接口 — 内存（离线默认）、Postgres/pgvector 和 Qdrant
- 可配置的、基于令牌的、分块并具有 markdown/标题感知
**智能代理**
- LangGraph 状态机：`guard_input → retrieve → plan → act → synthesize → guard_output`
- 函数/工具调用，支持 Pydantic 衍生的 JSON 模式；安全的 AST 计算器
- 模型上下文协议（MCP）— Atlas 既是 MCP **服务器** （暴露其知识库），又是 MCP **客户端** （使用外部工具）
- 跨 Claude、OpenAI、Ollama、vLLM 和 Bedrock 的成本感知多模型路由
- 令牌预算上下文打包，具有近似重复数据删除和基于来源的答案
- **设计忠实** — 答案严格基于检索的上下文；当未找到相关信息时，相关性门控使智能代理诚实地拒绝（“我当前没有相关来源”）并抑制引用，而不是凭空生成答案
**安全与治理**
- 输入和输出的防护措施：提示词注入检测、个人敏感信息删除（Presidio 和正则表达式备用）和内容过滤
- 红队/越狱抵抗套件（[data/redteam](data/redteam)）
**评估与 LLMOps**
- 评估框架，支持 RAG 指标（忠实度、答案相关性、上下文召回率），通过 LLM 评估，降级为确定性启发式方法离线
- 智能代理变体的 A/B 测试
- 每个聊天回合都经过一个接缝（`deps.run_chat`）：语义缓存查找（Redis，内存离线）→ 智能代理 → 成本核算 — 因此 `GET /metrics` 报告实时命中率和花费，重复问题在毫秒内无需模型即可返回
- Langfuse 跟踪在同一接缝上，以及 Claude 提供商中的提示缓存
**接口与基础设施**
- FastAPI 后端（REST + GraphQL + SSE 流式传输）和 Next.js/TypeScript 聊天界面
- 用于高吞吐量 URL 获取的并发 Go 导入工作器
- 用于本地开发的 Docker Compose；用于生产的 Kubernetes 清单和 AWS/GCP/Azure 部署说明；GitHub Actions CI
- 可选的 LoRA/PEFT 微调模块（Hugging Face Transformers + PEFT）
---
## 快速入门
### 一分钟内离线运行（无需 API 密钥，无需服务）
```bash
python3 -m venv .venv && source .venv/bin/activate # Python 3.11+
pip install pydantic pydantic-settings fastapi "uvicorn[standard]" httpx pytest pytest-asyncio rich
# 20 秒演示整个平台（导入 → 检索 → 防护措施 → 缓存 → 评估）
python -m atlas.cli demo
# 向智能代理提问（自动加载捆绑的示例知识库）
python -m atlas.cli chat -m "TR-1 保修期多久？"
# 运行测试套件（离线）
pytest -q
# 衡量 RAG 质量 — 并导出可共享的 Markdown 报告
python -m atlas.cli eval --suite rag_golden --report report.md
python -m atlas.cli redteam
# 提供 API + 交互式文档（自动加载开发环境中的示例语料库）
uvicorn atlas.api.main:app --port 8000 # -> http://localhost:8000/docs
```
在开发过程中，API 启动时加载捆绑的示例语料库，因此 `POST /chat` 立即返回基于来源的答案 — 无需手动导入步骤。`atlas demo` 通过一个命令演示：示例语料库导入、基于来源的答案、三个混合检索信号并排显示、阻止提示词注入攻击、语义缓存 MISS→HIT 加速和评估记分卡。一次性 `chat` 输出是 README 顶部的截图；`atlas eval --report` 生成类似 [docs/sample-eval-report.md](docs/sample-eval-report.md) 的报告。
两次询问相同的问题，第二次答案由语义缓存提供 — 检查 `GET /metrics` 以获取实时命中率、块计数和花费。
### 全栈（托管模型 + 真实数据存储）
```bash
cp .env.example .env # 添加您的 API 密钥 / DSN
make up # Postgres+pgvector, Redis, Qdrant, Langfuse, Ollama
make install # 完整依赖项集
make ingest # ETL -> 分块 -> 嵌入 -> 索引 -> 图谱
make api # http://localhost:8000/docs
```
运行 `make help` 以查看所有目标。
## 配置
所有配置均基于环境（12 因子）；查看 [.env.example](.env.example) 以获取完整配置。无需配置即可离线运行。设置以下任意配置即可启用相应集成：
| 变量 | 启用 |
|---|---|
| `ATLAS_PROVIDERS__ANTHROPIC_API_KEY` | 路由到 Claude |
| `ATLAS_PROVIDERS__OPENAI_API_KEY` | 路由到 OpenAI |
| `ATLAS_DB__DSN` | Postgres/pgvector 存储 |
| `ATLAS_REDIS__URL` | Redis 语义缓存 |
| `ATLAS_OBSERVABILITY__LANGFUSE_*` | Langfuse 跟踪 |
## 仓库布局
```
atlas/
core/ 共享 Pydantic 模型、协议接口、配置、日志
ingestion/ ETL、分块、嵌入、知识图谱提取
retrieval/ 混合搜索、RRF、重排序、图检索、向量存储
providers/ Claude / OpenAI / Ollama / vLLM / Bedrock 适配器
agent/ LangGraph 智能代理、模型路由器、工具、提示、上下文构建器
mcp/ MCP 工具服务器 + 客户端
guardrails/ 提示词注入、个人敏感信息删除、内容过滤器
evals/ 评估框架、RAG 指标、A/B 测试、红队
observability/ Langfuse 跟踪、Redis 语义缓存、成本/延迟跟踪
finetune/ 用于重排序器/意图分类器的 LoRA/PEFT 训练器
api/ FastAPI 应用（REST + GraphQL + 流式传输）
frontend/ Next.js + TypeScript 聊天界面
web/worker/ Go 并发导入工作器
infra/ Docker、Kubernetes、SQL、云（AWS/GCP/Azure）部署配置
tests/ pytest 套件
docs/ 架构和负责任 AI 文档
```
## 开发
```bash
pip install -e ".[dev]"
make test # pytest
make lint # ruff
make typecheck # mypy
```
欢迎贡献 — 查看 [CONTRIBUTING.md](CONTRIBUTING.md)。安全策略在 [SECURITY.md](SECURITY.md) 中。
## 许可证
[MIT](LICENSE).
