Airweave 开发者指南AI Agent 上下文检索层开源平台的架构与工程实践【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweaveAirweave 是一个开源的上下文检索层context retrieval layer平台它通过将 50 数据源同步进向量数据库让任意应用对 AI Agent 变得可搜索为 RAG 系统和 Agent 提供统一的检索底座。本文以仓库根目录的 CLAUDE.md 为主线结合 backend、frontend、mcp、monke 等目录的源码与配置完整梳理该平台的架构设计、常用命令、目录规范、代码风格、测试体系与关键工程契约帮助开发者快速上手二次开发与本地部署。读完本文你将掌握 Airweave 的端到端数据流Source → Embedding → Vector DB → Agent Query、四大组件的职责边界以及 backend/frontend 两个子项目的开发与测试实操。项目定位让任意应用对 AI Agent 可搜索Airweave 的定位非常聚焦作为 RAG 系统与 AI Agent 的上下文检索层。其核心思路是连接而非替代——它不自己做模型推理而是把散落在 Slack、Notion、HubSpot 等 50 外部系统中的数据通过统一的管道同步进向量数据库再以标准化的搜索接口暴露给 Agent。在 backend/pyproject.toml 中项目的描述为 Make any app searchable - Universal search and agent integration tool这与 CLAUDE.md 的定义完全一致。它不是一个又一个向量数据库而是一层把数据接入、实体抽取、变换、嵌入、检索串起来的编排层。总体架构四大组件与一条核心数据流CLAUDE.md 明确指出Airweave 是一个 monorepo包含四大组件组件目录技术栈BackendbackendPython 3.13、FastAPI、SQLAlchemy async、PostgreSQLFrontendfrontendReact 18、TypeScript、Vite、ShadCN UI、TailwindCSSWorkersbackend 内的 Temporal 域Temporal异步同步编排、Redispub/subMCP ServermcpNode.js、Streamable HTTP 传输供 AI 助手集成核心数据流为Sources → Entity extraction → Transformation (DAG) → Embedding → Vector DB → Agent queries从源码看这条链路在 backend 中各有落点platform/sources/承载 50 连接器Notion、Slack 等platform/entities/定义每个源的实体类型domains/sync_pipeline/实现同步管道与 DAG 变换domains/embedders/负责稠密/稀疏嵌入platform/destinations/与search/面向 Vespa 等向量检索最后通过 api/v1/endpoints/search.py 等路由暴露查询接口。整条链路由 Temporal 工作流异步编排见 docker/docker-compose.yml 中的temporal、temporal-worker服务定义。常用命令本地开发与一键编排本地开发Dockerstart.shCLAUDE.md 给出的核心入口是仓库根目录的 start.sh它不仅是启动脚本更是一个完整的本地环境编排器。其真实支持的选项比文档列出的更丰富--help输出start.sh完整如下./start.sh # 交互式安装 ./start.sh --skip-frontend # 仅启动后端 ./start.sh --skip-connect # 不启动 connect widget ./start.sh --skip-local-embeddings # 不启动本地嵌入服务约 2GB ./start.sh --enable-docling # 启用 docling-serve 本地 OCR ./start.sh --restart # 重启既有容器保留数据 ./start.sh --recreate # 停止并重建所有容器保留卷 ./start.sh --destroy # 彻底清理容器、卷与数据 ./start.sh --noninteractive # 跳过所有交互提示CI 场景 ./start.sh --verbose / --quiet # 调试 / 最小化输出脚本同时支持对应的环境变量NONINTERACTIVE1、SKIP_FRONTEND1、SKIP_LOCAL_EMBEDDINGS1、SKIP_CONNECT1、ENABLE_DOCLING1等便于 CI 注入。值得关注的是 start.sh 中的环境自举逻辑首次运行时若不存在.env会从.env.example复制一份自动用openssl rand -base64 32或 Pythonsecrets模块生成ENCRYPTION_KEY、STATE_SECRET、SVIX_JWT_SECRET、FIRST_SUPERUSER_PASSWORD、POSTGRES_PASSWORD并写入.env默认设置FIRST_SUPERUSERadminexample.com、POSTGRES_USERairweave并追加SKIP_AZURE_STORAGEtrue以加速本地启动交互式地提示配置OPENAI_API_KEY与MISTRAL_API_KEY。嵌入配置的选择逻辑start.sh遵循一个明确的优先级OpenAI1536 维 Mistral1024 维 本地 MiniLM384 维分别对应DENSE_EMBEDDER的openai_text_embedding_3_small、mistral_embed、local_minilm稀疏嵌入统一默认fastembed_bm25。这三个变量DENSE_EMBEDDER、EMBEDDING_DIMENSIONS、SPARSE_EMBEDDER是必须同时设置的——在 backend/airweave/core/config/settings.py 中它们没有默认值缺失会在导入时抛错。脚本还会通过 Compose profiles 决定启动哪些服务start.shlocal-embeddings、frontend、connect、vespa、docling均为可选 profile。启动完成后会做健康检查Vespa 就绪、后端/health可达并输出各服务地址Backend APIhttp://localhost:8001、Frontend UIhttp://localhost:8080、Connect Widgethttp://localhost:8082、Temporal UIhttp://localhost:8088、PostgreSQLlocalhost:5432、Vespahttp://localhost:8081、本地嵌入http://localhost:9878。BackendPoetry 驱动的 Python 工程cd backend poetry install # 安装依赖 poetry run uvicorn airweave.main:app --host 0.0.0.0 --port 8001 --reload # 开发服务器 # 测试 poetry run pytest tests/unit # 仅单元测试 poetry run pytest tests/integration # 集成测试 poetry run pytest tests/e2e # E2E 测试 poetry run pytest tests/unit/test_foo.py # 单个文件 poetry run pytest tests/unit/test_foo.py::test_bar # 单个用例 poetry run pytest -m not slow # 跳过慢测试 # 代码质量 poetry run ruff check . # Lint poetry run ruff format . # 格式化 poetry run black . # 备选格式化器88 字符 poetry run mypy airweave # 类型检查 lint-imports # 导入架构校验import-linter从 backend/pyproject.toml 可以验证这些命令背后的工具链约束Python 版本锁定3.13,3.14核心依赖包括fastapi ^0.115.12、sqlalchemy[asyncio] ^2.0.25、alembic、asyncpg、pydantic v2、temporalio、structlog等测试侧启用asyncio_mode auto异步测试函数自动识别内置unit、integration、live_integration、e2e、slow五个 marker代码质量由三套工具共同把关Ruff行宽 100、Google docstring、双引号、mypydisallow_untyped_defs true并启用pydantic.mypy插件、import-linter以airweave为根包做架构分层校验。后端启动入口 backend/airweave/main.py 展示了应用生命周期lifespan 中先初始化 DI 容器fail fast再按RUN_ALEMBIC_MIGRATIONS设置执行alembic upgrade head随后init_db、校验嵌入配置、初始化系统级 Temporal schedules最后挂载 metrics 与 DB 池采样器。FrontendVite React 工程cd frontend npm install # 安装依赖 npm run dev # 开发服务器:8080 npm run build # 生产构建 npm run lint # ESLintfrontend/package.json 还提供了npm testvitest run与npm run test:watch以及npm run build:devdevelopment 模式构建。依赖中值得注意的工程选型tanstack/react-query服务端状态、zustand全局状态、sonnerToast、zod校验、posthog-js产品分析、auth0/auth0-react身份认证。Backend 目录结构分层清晰的服务端骨架CLAUDE.md 给出了 backend 的完整目录树结合仓库实际文件backend/airweave可确认其分层职责backend/airweave/ ├── api/v1/endpoints/ # FastAPI 路由处理器每个资源一个 router ├── models/ # SQLAlchemy ORM 模型UUID 主键 ├── schemas/ # Pydantic 请求/响应 schema ├── crud/ # 数据库访问基类_base_organization, _base_user, _base_public ├── domains/ # 业务逻辑每个域含 service.py, repository.py, protocols.py ├── platform/ │ ├── sources/ # 50 源连接器Notion、Slack 等 │ ├── destinations/ # 向量数据库适配器 │ ├── embedding_models/# 嵌入提供商 │ ├── entities/ # 每个源的实体类型定义 │ └── temporal/ # Temporal worker 与 activities ├── core/ │ ├── config/ # Pydantic Settings环境变量 │ ├── container/ # 依赖注入容器 factory │ ├── exceptions.py # 自定义异常层级 │ └── logging.py # 基于 structlog 的日志 ├── adapters/ # 外部服务适配器PostHog、Stripe 等 └── search/ # 搜索提供商VespaAPI 路由层扁平化 REST 设计API 路由统一在 api/v1/api.py 中注册前缀覆盖了平台的核心资源域/health、/api-keys、/users、/organizations、/billing、/usage、/sources、/auth-providers、/collections、/source-connections、/source-rate-limits、/sync、/entities、/entity-counts、/files、/admin、/webhooks、/connect。一个值得注意的设计是 api/router.py 中的TrailingSlashRouter它同时注册带斜杠与不带斜杠两个路由带斜杠版本include_in_schemaFalse并在 main.py 中显式关闭 FastAPI 内置的斜杠重定向redirect_slashesFalse。这意味着客户端访问/collections与/collections/都能命中但 OpenAPI schema 中只暴露规范形式。请求上下文ApiContext 贯穿每个端点CLAUDE.md 强调ApiContextis injected into every endpoint — contains user, org, logger, cache, rate limiter。其实现位于 api/context.pyApiContext(BaseContext)是一个 dataclass在BaseContextorganization、logger、feature-flag helpers之上追加用户身份、request_id、auth_methodSYSTEM/API_KEY/AUTH0/INTERNAL_SYSTEM、auth_metadata与请求头结构化信息提供is_api_key_auth、is_user_auth等便捷属性to_serializable_dict()可将上下文序列化后传入 Temporal workflow 供 activities 重建ConnectContext是面向 Connect 会话的变体无用户、无 Auth0 token用 HMAC 会话 token 限定到某个 collection通过client_nameairweave-connect供分析系统识别 Connect 流量。依赖注入Container 持有、Factory 构建CLAUDE.md 描述的协议化 DI 在 core/container/container.py 中有完整实现。设计原则直接写在 docstring 里Container serves, factory builds; Fail fast: all construction at startup; Type safety: fields are protocol types; Testing: construct directly with fakes。Container是一个frozenTrue的 dataclass字段类型全部是协议Protocol类型覆盖 context cache、rate limiter、health、event bus、pubsub、webhook、circuit breaker、metrics、source 注册表、collection、browse tree、OAuth、sync、access control、billing、usage、identity、email、embedder 注册表、connect、search 域instant/classic/agentic/browse、storage、ARF、converter 等 60 依赖测试中可用container.replace(event_busFakeEventBus())做局部覆盖或直接用 fakes 构造端点侧通过from airweave.api.deps import Inject以Inject(EventBus)形式按需拉取协议实现。配置系统Pydantic Settings 与强校验core/config/settings.py 是全部环境变量的权威定义CLAUDE.md 提及的核心项均可在此找到并扩展数据库POSTGRES_HOST/PORT/DB/USER/PASSWORD、POSTGRES_SSLMODE默认preferSQLALCHEMY_ASYNC_DATABASE_URI会在未显式设置时用 asyncpg 协议自动组装RedisREDIS_HOST/PORT/PASSWORD/DB默认 localhost:6379/0用于 pub/sub 与缓存嵌入DENSE_EMBEDDER、EMBEDDING_DIMENSIONS、SPARSE_EMBEDDER三件套必需TEXT2VEC_INFERENCE_URL默认http://localhost:9878指向本地 transformers 推理服务VespaVESPA_URL、VESPA_PORT8081、VESPA_TIMEOUT、VESPA_CLUSTERTemporalTEMPORAL_HOST/PORT/NAMESPACE/TASK_QUEUE任务队列默认airweave-sync-queue存储后端STORAGE_BACKEND支持 filesystem/azure/aws/gcp未设置时按环境自动解析local/test → filesystemdev/prd → azure安全与校验STATE_SECRET与SVIX_JWT_SECRET均强制 ≥32 字符FIRST_SUPERUSER_PASSWORD在非本地环境拒绝弱口令内置 banned 名单与占位邮箱adminexample.com等AUTH_ENABLEDTrue时强制要求全部 Auth0 配置同步与限流SYNC_MAX_WORKERS默认 20、SYNC_THREAD_POOL_SIZE100、WEB_FETCHER_MAX_CONCURRENT10、OPENAI_MAX_CONCURRENT20、API_REQUEST_BODY_SIZE_LIMIT默认 10MB、API_REQUEST_TIMEOUT_SECONDS60计费与分析STRIPE_ENABLED开启时强校验 Stripe 密钥POSTHOG_API_KEY提供默认公共 keyANALYTICS_ENABLED默认开启。中间件与异常体系main.py 按先注册者最外层的顺序挂载了完整的中间件链add_request_id→http_metrics_middleware尽早捕获端到端延迟与 413/408/429 计数→request_body_size_middleware→request_timeout_middleware→rate_limit_headers_middleware→log_requests→analytics_middleware→exception_logging_middleware最后是支持白标扩展的DynamicCORSMiddleware本地环境追加*。异常处理覆盖RequestValidationError、PermissionException、NotFoundException、RateLimitExceededException、InvalidStateError、InvalidInputError及自定义的AirweaveException基类保证错误响应风格统一。关键概念short_name 与迁移CLAUDE.md 强调两个关键约定short_name是 source/entity 的全局唯一标识如slack、hubspot_crm贯穿平台/sources 下的连接器命名与 monke 测试框架的文件组织Alembic 迁移随启动自动执行RUN_ALEMBIC_MIGRATIONS默认 True迁移脚本位于 backend/alembic/versions基线为0000_baseline.py由 lifespan 中的alembic upgrade head自动推进。Frontend 目录结构特性分组的组件体系frontend/src/ ├── components/ │ ├── ui/ # ShadCN 基础组件40 │ └── [feature]/ # 按特性分组的组件 ├── pages/ # 路由级组件 ├── lib/ │ ├── api.ts # API 客户端token 管理、org 上下文、SSE、重试 │ ├── stores/ # Zustand storesorganizations、collections 等 │ ├── auth-context.tsx # Auth0 封装含开发模式回退 │ └── validation/ # 基于 Zod 的校验规则 ├── hooks/ # 自定义 React hooks ├── config/ # env.ts、auth.ts └── types/index.ts # 共享 TypeScript 类型镜像后端 Pydantic schemas关键工程模式CLAUDE.md 原述仓库均有对应实现API 客户端一律使用相对路径不带/api/v1前缀例如apiClient.get(/collections)这与后端版本不进 URL 路径的 REST 约定互为表里自动注入请求头X-Organization-ID与X-Airweave-Session-ID用于 PostHog 会话回放状态管理分层Zustand 管全局状态、React Query 管服务端状态、组件内 state 只处理 UI 级关注点组件内顺序hooks → effects → handlers → render路径别名/映射到./src见 frontend/vite.config.ts。代码风格规范两套语言、同一套纪律BackendPythonRuff 规则行宽 100、Google 风格 docstring、双引号字符串见 backend/pyproject.toml 的[tool.ruff]开启 E/W/F/I/C/B/D 系列并显式忽略B008、B904所有 I/O 一律 asyncasyncio_mode auto保证异步测试开箱即用参数与返回值必须类型标注单函数控制在 50 行以内RESTful 端点版本不是 URL 路径的一部分统一为host.com/{endpoint}日志统一从ctxAPI 场景或sync_context同步场景获取安全红线禁止用random.*生成安全相关值Ruff S311必须使用secrets模块。日志实现见 core/logging.pyLoggerConfigurator.configure_logger()在LOCAL_DEVELOPMENTTrue时输出人类可读文本否则输出 JSON 结构化日志兼容 Azure Log Analytics / Prometheus / GrafanaContextualLogger支持with_context(organization_id...)、with_prefix(ERROR: )等链式组合把request_id、user_id、auth_method自动注入日志维度。FrontendTypeScriptTailwindCSS 配合cn()工具函数合并类名严格类型共享接口统一放types/index.ts禁止Math.random()ESLint ban改用crypto.getRandomValues()或crypto.randomUUID()Toast 通知统一走 Sonnertoast.success()、toast.error()等。测试体系分层标记与端到端框架Backend 测试标记CLAUDE.md 与 backend/pyproject.toml 共同确认了五个 pytest markerMarker语义unit快速、隔离的单元测试integration需要数据库/服务live_integration需要真实云基础设施e2e端到端测试slow长时间运行的测试异步模式为auto异步测试函数会被自动检测默认testpaths [tests, airweave]且带--covairweave覆盖率统计。测试目录位于 backend/tests按 unit / integration / e2esmoke分层组织。Monke外部系统真实数据的 E2E 框架CLAUDE.md 特别介绍了 monke 这一独特的 E2E 测试框架它通过在外部系统创建真实测试数据、触发同步、并在搜索索引中校验结果来端到端验证 source 连接器。三个组成部分monke/bongos/{short_name}.py— 测试数据创建与清理如monke/bongos/notion.pymonke/generation/schemas/{short_name}.py— 生成 schemamonke/configs/{short_name}.yaml— 测试配置。每个 source 的short_name如slack直接决定了这三个文件的命名体现了short_name 全局唯一标识这一核心约定的贯彻。monke 还包含独立的 auth 层monke/auth/broker.py、credentials_resolver.py与 backend runnermonke/backend/app.py。OAuth 浏览器流程契约必须遵守的三步协议CLAUDE.md 记录的浏览器 OAuth 流程是一个硬性契约违反它会导致同步卡死在PENDINGPOST /source-connections返回auth.claim_token→ 存入sessionStoragekey 为oauth_claim_token:{source_connection_id}OAuth 重定向回调后调用POST /source-connections/{id}/verify-oauthbody 携带{ claim_token }只有 verify-oauth 成功响应后才移除 sessionStorage 条目。跳过第 2 步会让 sync 永远停留在PENDING状态。这条契约在 connect 前端connect/src的 OAuth 流程与 backend 的source_connections端点中均有对应实现是排查连接成功后不同步类问题时的首要检查点。基础设施说明从开发到生产基础设施由相邻的infra-core仓库管理开发用 Docker Compose生产用 Kubernetes核心中间件PostgreSQL元数据、Redispub/sub 缓存、Vespa/Qdrant向量、Temporal编排用户认证用 Auth0本地开发可设AUTH_ENABLEDFalse关闭pre-commit hooks 强制执行 ruff、mypy、import-linter、ESLint。从 docker/docker-compose.yml 可以看到开发环境完整服务矩阵postgres:16200 连接、256MB shared_buffers、redis:7-alpine、backend挂载../backend热重载附host.docker.internal用于 webhook E2E、frontend/connectprofile 控制、text2vec-transformers本地嵌入all-MiniLM-L6-v2、temporal/temporal-worker/temporal-uiUI 在 8088 端口、vespa:8单节点 vespa-init自动部署 vespa/app 应用包、可选的doclingOCR与svixwebhook 分发数据落 PostgreSQL 的svix库。小结CLAUDE.md 以极简的篇幅勾勒了 Airweave 的全貌而仓库源码则把每一行抽象落成了可运行的工程。贯穿全文的三条主线值得开发者牢记数据流主线Sources → Entity extraction → Transformation (DAG) → Embedding → Vector DB → Agent queries所有组件都服务于这条管道工程契约主线short_name全局唯一命名、ApiContext注入、Container协议化 DI、OAuth 三步验证、前端相对路径 API——这些约定是代码库自洽运转的粘合剂质量防线主线Ruff/mypy/import-linter 三层静态检查、五级 pytest marker、monke 真实数据 E2E、pre-commit 强制钩子共同保证了 50 连接器规模下的可持续迭代。无论你是要接入一个新的数据源、调试一条同步管道还是为 Agent 集成搜索能力都可以从本文梳理的目录结构与命令入口出发在 CLAUDE.md 与对应源码的配合下快速定位并深入。【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweave创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考