Ratel：AI Agent 的上下文工程层

图1：Ratel 核心机制演示动画（来源：ratel-AI/ratel 官方仓库）

---

一、痛点场景：你的 AI Agent 在为「垃圾上下文」买单

想象一下：你给 AI Agent 装了 30 个工具、15 个技能（Skills）和一堆系统指令。每次对话时，Agent 不管用不用得着，先把所有工具的 Schema、所有技能的说明、所有指令全塞进上下文窗口一起发出去。

结果呢？

• 费用爆炸：每个工具 Schema 200-500 token，每次调用都白白浪费。更糟糕的是，你的 Agent 每轮对话都在支付这些「沉默成本」。
• 准确率崩塌：上下文窗口越来越臃肿，模型开始「选错工具」——明明要搜索文件，模型却调用了数据库连接器。大海捞针式的上下文让模型迷失在无关信息中。
• 响应变慢：token 越多，LLM 推理时间越长，端到端延迟直线上升。

这就是当前主流 AI Agent 框架的通病：全量加载、无差别注入的上下文策略，已经成为 AI Agent 落地的核心瓶颈。

---

二、Ratel 是什么

Ratel 是由 Agentified 团队开源的 AI Agent 上下文工程（Context Engineering）中间件层。它的核心理念是：

不给 Agent 全量上下文，而是让 Agent 按需「检索」——只注入当前任务真正需要的工具和技能。

这就好比一个专业木匠的工具箱，而不是把所有工具都摊在桌面上。Agent 需要锤子时，就从索引中检索锤子；需要螺丝刀时，再去索引中检索螺丝刀。按需索取，精准高效。

Ratel 的核心技术特点：

特性	说明
渐进式披露（Progressive Disclosure）	Agent 分轮次检索，每次只获取当前 turn 所需的最少工具/技能
本地 BM25 检索	纯 Rust 实现，无需外部依赖，零配置启动
语义检索（可选）	内置 Candle 推理引擎加载 HuggingFace embedding 模型，支持本地语义相似度搜索
混合搜索	BM25 + 语义混合模式，兼顾关键词精确匹配和语义相关性
无需向量数据库	区别于传统 RAG 方案，不依赖外部向量数据库（Pinecone/Milvus 等）
多框架适配	官方支持 Vercel AI SDK、Pydantic AI、Mastra 适配器

---

三、核心架构解析

3.1 技术栈

Ratel 是一个 Rust + TypeScript + Python 三语言混合的 Monorepo 项目：

ratel-AI/ratel (Monorepo)
├── src/core/          # Rust 核心引擎 (ratel-ai-core)
├── src/sdk/           # TypeScript SDK + Python SDK
├── src/adapters/      # 框架适配器（Vercel AI SDK、Mastra）
└── src/telemetry/     # 可观测性模块

Rust 核心（ratel-ai-core）负责高性能检索逻辑：

• BM25 检索：bm25-rs 2.3（Rust 实现的 Okapi BM25 算法）
• 语义检索：基于 candle-core / candle-nn / candle-transformers，支持纯 Rust 加载 HuggingFace embedding 模型（如 BGE、MiniLM），无需 C++/ONNX 依赖
• 分词：使用 tokenizers（HuggingFace tokenizer 的 Rust 版本，支持 fancy-regex 后端避免 C 依赖）
• HTTP 客户端：使用 ureq + rustls（无 OpenSSL 依赖），支持 OpenAI 兼容的 embedding 接口（OpenAI、Ollama、TEI、vLLM）

TypeScript SDK（@ratel-ai/sdk）通过 Rust 原生插件（cdylib）提供 Node.js 接口，兼顾性能和生态兼容性。

Python SDK 通过 Rust 原生扩展提供 Python 接口，无缝集成到 Pydantic AI 等 Python Agent 框架中。

3.2 核心检索流程

Agent 请求工具/技能
        ↓
  search_capabilities(query)
        ↓
  [BM25 / 语义 / 混合] 检索
        ↓
  返回 top-K 相关工具 & 技能
        ↓
  Agent 注入最少必要上下文

用户只需调用 search_capabilities_tool() 获取候选工具列表，再调用 invoke_tool_tool() 执行具体工具。这两个工具可以像普通 LLM Tools 一样直接注册到 Vercel AI SDK 或 Pydantic AI 中。

3.3 存储层设计

Ratel 使用 indexmap 2（保持插入顺序的 HashMap）存储工具和技能注册表，支持重复注册时原地替换，避免 ID 重复问题。底层索引结构支持 BM25 和语义向量两种检索模式，通过配置文件（context7.json）切换。

---

四、快速上手

通过 npm 安装（TypeScript）

pnpm add @ratel-ai/sdk

通过 pip 安装（Python）

pip install ratel-ai

集成 Vercel AI SDK

import { Ratel } from "@ratel-ai/adapters-vercel-ai-sdk";

// Ratel 自动接管工具注册和调用逻辑
const ratel = new Ratel({
  tools: [/* 你的工具列表 */],
  skills: [/* 你的技能列表 */],
  retrieval: "bm25", // 或 "semantic" / "hybrid"
});

集成 Pydantic AI

from ratel_ai import ToolCatalog, SkillCatalog, search_capabilities_tool

catalog = ToolCatalog()
# 注册你的工具...
tools = [search_capabilities_tool(catalog, skills)]

---

五、与传统 RAG 的核心差异

维度	传统 RAG	Ratel
检索对象	文档/知识库	Agent 工具 & 技能
向量数据库	必须（Milvus/Pinecone）	不需要
上下文策略	一次性加载所有相关文档	分轮次按需渐进披露
部署复杂度	高（需要维护向量数据库）	极低（纯 SDK，一个命令安装）
适用场景	知识问答、文档检索	AI Agent 工具选择优化

Ratel 解决的本质问题是：不是让 Agent 记住所有工具，而是在需要时快速找到正确的工具。这和传统 RAG 解决「从海量文档中找答案」的思路完全不同，但精神内核一致——减少无关上下文，提升模型准确性。

---

六、局限性与争议

1. 纯客户端 SDK：Ratel 目前是纯 SDK，没有服务端组件。如果你的 Agent 部署在纯服务端（如 Claude API 直接调用），Ratel 需要在你的服务端代码中运行，而不是独立部署。
2. 工具 Schema 的初始注册：Agent 需要在启动时注册所有工具 Schema，这个 Schema 本身仍然占据上下文。但一旦注册完成，后续每轮检索只注入最相关的子集，相比全量注入已经大幅节省。
3. 语义检索的冷启动：首次使用语义检索时需要下载 HuggingFace embedding 模型（约 100-500MB），在网络不佳的环境可能遇到瓶颈。
4. 框架绑定：虽然 Ratel 提供了 Vercel AI SDK 和 Pydantic AI 适配器，但如果你的 Agent 框架不在支持列表中，需要自己实现适配逻辑。

---

七、行业意义与未来展望

Ratel 的出现代表了 AI Agent 开发范式的一个新趋势：从全量上下文向精准上下文演进。随着 Agent 接入的工具越来越多（30+、50+），上下文成本将成为不可忽视的问题。Ratel 率先在这一领域给出了开源、免费、无供应商锁定的解决方案。

目前 Ratel 的 benchmark（benchmark.ratel.sh）展示了在多种模型配置下的 token 节省效果和准确率恢复数据，感兴趣的同学可以去官网查看详细报告。

---

附录：项目基本信息

属性	值
Stars	351
语言	TypeScript / Rust / Python
License	Apache-2.0 + MIT（双许可证）
主分支	main
官网	https://www.ratel.sh
文档	https://docs.ratel.sh
Discord	https://discord.gg/75vAPdjYqT
核心依赖	bm25-rs, candle (HuggingFace), tokenizers