airweave · 协议与工具集成

让 AI Agent 真正「读懂」你的数据

想象一个场景：你训练了一个非常聪明的 AI 助手，但当用户问起「上个月销售额是多少」时，AI 只能尴尬地回答「我没有访问你的数据库」。这就是大多数 AI Agent 面临的上下文饥渴问题——模型再强，没有数据也是无米之炊。

Airweave 正是来解决这个问题的。它的核心理念是：给 AI Agent 安装一个「万能数据接口」，让 Agent 可以实时查询任何应用、任何数据库里的数据，就像人类使用搜索框一样自然。

背景：为什么 Agent 都需要 RAG？

RAG（检索增强生成）并不是新概念，但真正让它在 Agent 时代大放异彩的，是 airweave 的创始团队。他们在大量企业落地 AI 项目时发现：传统 RAG 方案过于死板，只能处理文档，无法应对 CRM、ERP、数据库这类结构化数据源。

项目于 2024 年 12 月正式开源，由 Rauf Akdemir 和 Lennert Jansen 两位核心开发者主导。创始团队拥有企业搜索和数据集成背景，曾在 Elasticsearch、Vespa 等开源搜索引擎领域有丰富经验。短短不到半年时间，GitHub 标星数突破 6300+，成为 2025 年 AI Infra 领域增长最快的开源项目之一。

项目目前已发布云托管版本（app.airweave.ai），同时维护完整的开源版本。

类比：像一个「万能翻译官」

你可以把 Airweave 理解为一个多语言翻译官团队。企业里的各种数据系统（Salesforce、Notion、PostgreSQL）就像来自不同国家的人，说着不同的「语言」—— 有的是关系数据库的 SQL，有的是 API 的 JSON，有的是 GraphQL。

Airweave 的数据连接器（Connectors）就是这些翻译官，他们把每种语言翻译成 AI 能理解的「向量语义」，然后统一存储到向量数据库（如 Vespa）中。当 AI Agent 需要查询时，一个统一的 API 就能搞定所有数据源的检索。

这和传统 ETL 方案的本质区别在于：Airweave 不是把数据「搬家」到一个新地方，而是建立了一个实时同步的语义索引层，数据和源头保持同步，AI 查询到的永远是最新的。

核心功能：50+ 数据源 + 全链路向量检索

多源数据连接器

Airweave 目前支持 50+ 种数据源，涵盖主流 SaaS、企业软件和数据库：

CRM/销售：HubSpot、Salesforce、Zendesk
协作/文档：Notion、Google Drive、Confluence、Slack
数据库：PostgreSQL、MySQL、MongoDB、Neo4j
搜索/内容：Elasticsearch、Vespa、Web 抓取（Firecrawl）
云存储：S3、Google Cloud Storage、Azure Blob
消息：Gmail、Outlook

每个连接器都实现了增量同步，只拉取自上次同步后的变更数据，避免重复索引。同步调度支持 Cron 表达式，可以精确控制同步频率。

向量检索与语义匹配

项目使用 FastEmbed（基于 e5-mistral 模型）作为默认嵌入模型，支持自定义 embedding provider。底层向量数据库默认使用 Vespa（也是本项目的同家母公司出品），同时支持 Pinecone、Weaviate、Qdrant 等主流向量数据库。

特别值得一提的是 chonkie（项目自研或重度依赖的语义分块库），支持基于语义的智能分块（semantic chunking），比传统的固定长度分块能更好地保留语义完整性，对长文档检索效果提升明显。

AI Agent 集成层

Airweave 提供了丰富的 Agent 集成方式：

OpenAI Assistants API 集成
MCP（Model Context Protocol） 协议支持，Claude Desktop 可直接连接
Fern 生成的 API 文档，开发者体验友好
Python SDK + REST API 双接口

Agent 通过 `search()` 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。

技术架构：Monorepo 四层结构

项目采用成熟的前后端分离 monorepo 架构：

backend/        Python 3.13 + FastAPI + SQLAlchemy async
frontend/       React 18 + Vite + TypeScript + Radix UI + TailwindCSS
connect/        数据连接器 SDK
mcp/            MCP Server 实现
vespa/          Vespa 配置

后端技术栈：

FastAPI 作为 API 框架，自带 OpenAPI 文档
PostgreSQL 16 作为主数据库（asyncpg 异步驱动）
Redis 7 用于缓存和消息队列
Temporal 工作流引擎处理长时同步任务（如大型数据库的初次全量索引）
SQLAlchemy 2.0 async，全程异步，吞吐量高
依赖注入：pydantic-settings + python-dotenv
认证：Auth0 + JWT（python-jose）
可观测性：Prometheus metrics + structlog 结构化日志

前端技术栈：

React 18 + TypeScript
Vite 构建工具（开发体验极佳）
TailwindCSS + Radix UI（无样式组件，纯语义化 UI）
TanStack Query（服务端状态管理）
framer-motion 动画
Auth0 React SDK

整体代码质量较高：完整的 pytest 测试套件（pytest-asyncio + pytest-cov）、pre-commit 钩子（black/isort/mypy）、CI/CD GitHub Actions。

上手体验：开箱即用 vs. 深度定制

快速体验（推荐小白）

克隆仓库，执行 ./start.sh，脚本自动完成：生成密钥、创建 .env、启动所有 Docker 服务（postgres、redis、backend、frontend）、健康检查。整个过程约 10-20 分钟，无需手动配置。

启动后访问 http://localhost:8080 进入 Web UI，首次使用需要配置 Auth0 或禁用认证（AUTH_ENABLED=false）。

深度定制（推荐开发者）

monke.sh 是项目的测试运行脚本，提供多种运行模式：

本地开发模式（跳过 Docker，直接 Python 运行）
外部 embedding provider（如 OpenAI、Mistral、Cohere）
Azure Key Vault 集成

连接新数据源只需在 connect/ 目录下实现对应的 connector class，框架自动发现和加载。

注意：本地部署需要 Docker，无纯 Python 部署路径。Python 版本要求 3.13（相对较新，部分系统可能需要手动安装）。

局限与挑战

开源版本 vs. 云版本的差距

开源版本缺少一些云端专属功能，如高级权限管理、审计日志、多租户隔离等。对于中型企业来说，直接使用开源版本可能需要额外的开发工作。

运维复杂度

docker-compose 模式下服务依赖较多（postgres + redis + backend + frontend + temporal），初次调试需要理解各服务间的通信关系。对于没有 Docker 经验的团队来说有一定门槛。

中文社区支持

文档和社区目前以英文为主，中文资料较少，对国内团队不太友好。

数据隐私

所有数据默认存储在本地 PostgreSQL 和 Vespa 中，无数据上传到第三方。Auth0 认证也支持自托管，适合对数据主权有要求的企业。

行业意义：下一代 RAG 的方向标

Airweave 的出现代表了 RAG 领域的一个重要趋势：从「文档检索」向「实时数据检索」的范式转移。传统的 RAG 系统只能处理静态文档，而 Airweave 证明了结构化数据源的实时语义检索是完全可行的。

从增长数据看，项目 Star 数从 2025 年初的 1000+ 增长到现在的 6300+，月均增长约 800 Star，增速在同类项目中处于第一梯队。话题标签覆盖了从 RAG、Agent 到 Enterprise Data 的完整链路，说明项目定位足够宽泛。

MCP 协议的集成尤其值得关注。Anthropic 推动的 MCP 正在成为 AI Agent 工具调用的行业标准，Airweave 早早支持意味着它可以无缝接入 Claude Desktop、Cursor Agent 等主流 Agent 产品，长期生态潜力巨大。

让 AI Agent 真正「读懂」你的数据

Airweave 正是来解决这个问题的。它的核心理念是：给 AI Agent 安装一个「万能数据接口」，让 Agent 可以实时查询任何应用、任何数据库里的数据，就像人类使用搜索框一样自然。

背景：为什么 Agent 都需要 RAG？

项目目前已发布云托管版本（app.airweave.ai），同时维护完整的开源版本。

类比：像一个「万能翻译官」

这和传统 ETL 方案的本质区别在于：Airweave 不是把数据「搬家」到一个新地方，而是建立了一个实时同步的语义索引层，数据和源头保持同步，AI 查询到的永远是最新的。

核心功能：50+ 数据源 + 全链路向量检索

多源数据连接器

Airweave 目前支持 50+ 种数据源，涵盖主流 SaaS、企业软件和数据库：

CRM/销售：HubSpot、Salesforce、Zendesk
协作/文档：Notion、Google Drive、Confluence、Slack
数据库：PostgreSQL、MySQL、MongoDB、Neo4j
搜索/内容：Elasticsearch、Vespa、Web 抓取（Firecrawl）
云存储：S3、Google Cloud Storage、Azure Blob
消息：Gmail、Outlook

每个连接器都实现了增量同步，只拉取自上次同步后的变更数据，避免重复索引。同步调度支持 Cron 表达式，可以精确控制同步频率。

向量检索与语义匹配

AI Agent 集成层

Airweave 提供了丰富的 Agent 集成方式：

OpenAI Assistants API 集成
MCP（Model Context Protocol） 协议支持，Claude Desktop 可直接连接
Fern 生成的 API 文档，开发者体验友好
Python SDK + REST API 双接口

Agent 通过 `search()` 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。

技术架构：Monorepo 四层结构

项目采用成熟的前后端分离 monorepo 架构：

backend/        Python 3.13 + FastAPI + SQLAlchemy async
frontend/       React 18 + Vite + TypeScript + Radix UI + TailwindCSS
connect/        数据连接器 SDK
mcp/            MCP Server 实现
vespa/          Vespa 配置

后端技术栈：

FastAPI 作为 API 框架，自带 OpenAPI 文档
PostgreSQL 16 作为主数据库（asyncpg 异步驱动）
Redis 7 用于缓存和消息队列
Temporal 工作流引擎处理长时同步任务（如大型数据库的初次全量索引）
SQLAlchemy 2.0 async，全程异步，吞吐量高
依赖注入：pydantic-settings + python-dotenv
认证：Auth0 + JWT（python-jose）
可观测性：Prometheus metrics + structlog 结构化日志

前端技术栈：

React 18 + TypeScript
Vite 构建工具（开发体验极佳）
TailwindCSS + Radix UI（无样式组件，纯语义化 UI）
TanStack Query（服务端状态管理）
framer-motion 动画
Auth0 React SDK

整体代码质量较高：完整的 pytest 测试套件（pytest-asyncio + pytest-cov）、pre-commit 钩子（black/isort/mypy）、CI/CD GitHub Actions。

上手体验：开箱即用 vs. 深度定制

快速体验（推荐小白）

启动后访问 http://localhost:8080 进入 Web UI，首次使用需要配置 Auth0 或禁用认证（AUTH_ENABLED=false）。

深度定制（推荐开发者）

monke.sh 是项目的测试运行脚本，提供多种运行模式：

本地开发模式（跳过 Docker，直接 Python 运行）
外部 embedding provider（如 OpenAI、Mistral、Cohere）
Azure Key Vault 集成

连接新数据源只需在 connect/ 目录下实现对应的 connector class，框架自动发现和加载。

注意：本地部署需要 Docker，无纯 Python 部署路径。Python 版本要求 3.13（相对较新，部分系统可能需要手动安装）。

局限与挑战

开源版本 vs. 云版本的差距

开源版本缺少一些云端专属功能，如高级权限管理、审计日志、多租户隔离等。对于中型企业来说，直接使用开源版本可能需要额外的开发工作。

运维复杂度

中文社区支持

文档和社区目前以英文为主，中文资料较少，对国内团队不太友好。

数据隐私

让 AI Agent 真正「读懂」你的数据

Airweave 正是来解决这个问题的。它的核心理念是：给 AI Agent 安装一个「万能数据接口」，让 Agent 可以实时查询任何应用、任何数据库里的数据，就像人类使用搜索框一样自然。

背景：为什么 Agent 都需要 RAG？

项目目前已发布云托管版本（app.airweave.ai），同时维护完整的开源版本。

类比：像一个「万能翻译官」

这和传统 ETL 方案的本质区别在于：Airweave 不是把数据「搬家」到一个新地方，而是建立了一个实时同步的语义索引层，数据和源头保持同步，AI 查询到的永远是最新的。

核心功能：50+ 数据源 + 全链路向量检索

Agent 通过 search() 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。

技术架构：Monorepo 四层结构

整体代码质量较高：完整的 pytest 测试套件（pytest-asyncio + pytest-cov）、pre-commit 钩子（black/isort/mypy）、CI/CD GitHub Actions。

上手体验：开箱即用 vs. 深度定制

注意：本地部署需要 Docker，无纯 Python 部署路径。Python 版本要求 3.13（相对较新，部分系统可能需要手动安装）。

局限与挑战

所有数据默认存储在本地 PostgreSQL 和 Vespa 中，无数据上传到第三方。Auth0 认证也支持自托管，适合对数据主权有要求的企业。

行业意义：下一代 RAG 的方向标

让 AI Agent 真正「读懂」你的数据

Airweave 正是来解决这个问题的。它的核心理念是：给 AI Agent 安装一个「万能数据接口」，让 Agent 可以实时查询任何应用、任何数据库里的数据，就像人类使用搜索框一样自然。

背景：为什么 Agent 都需要 RAG？

项目目前已发布云托管版本（app.airweave.ai），同时维护完整的开源版本。

类比：像一个「万能翻译官」

这和传统 ETL 方案的本质区别在于：Airweave 不是把数据「搬家」到一个新地方，而是建立了一个实时同步的语义索引层，数据和源头保持同步，AI 查询到的永远是最新的。

核心功能：50+ 数据源 + 全链路向量检索

Agent 通过 search() 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。

技术架构：Monorepo 四层结构

整体代码质量较高：完整的 pytest 测试套件（pytest-asyncio + pytest-cov）、pre-commit 钩子（black/isort/mypy）、CI/CD GitHub Actions。

上手体验：开箱即用 vs. 深度定制

注意：本地部署需要 Docker，无纯 Python 部署路径。Python 版本要求 3.13（相对较新，部分系统可能需要手动安装）。

局限与挑战

所有数据默认存储在本地 PostgreSQL 和 Vespa 中，无数据上传到第三方。Auth0 认证也支持自托管，适合对数据主权有要求的企业。

行业意义：下一代 RAG 的方向标

Agent 通过 `search()` 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。

Agent 通过 `search()` 方法传入自然语言查询，Airweave 自动完成查询改写（Query Rewriting）→ 向量检索 → 重排序（Reranking）→ 返回结构化上下文。