Airweave 的 Fern 模块API 文档与多语言 SDK 的自动化生成管线【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweave导读本文聚焦 Airweave 开源仓库中的fern/目录完整拆解该项目如何借助 Fern 平台从 FastAPI 应用自动导出经过筛选与定制的 OpenAPI 规范再一键生成 Pythonairweave-sdk与 TypeScriptairweave/sdk两套官方 SDK 以及在线 API 文档。读完本文你将掌握 Airweave 文档管线中每条配置文件的真实作用、本地一键生成命令的执行链路以及如何通过 Overrides 与白名单机制控制对外暴露的 API 面。一、fern/目录在 Airweave 中的定位Airweave 是一个面向 AI Agent 的开源上下文检索层context retrieval layer其核心能力集中在backend/airweave/api下的 FastAPI 路由见 backend/airweave/api。而fern/目录是这套服务对外产品化的关键一环它承载了 Airweave 官方 API 文档的定义、站点配置以及 SDK 的生成配置。按照 fern/README.md 的描述该目录的职责是This directory contains the Fern API definition and configuration for Airweaves API documentation and SDK generation.即为 Airweave 的 API 文档与 SDK 生成提供 Fern 侧的 API 定义与配置。它是连接后端实现与开发者体验之间的装配车间。目录结构总览fern/ ├── definition/ # API 定义文件含 Overrides 与生成的 OpenAPI │ ├── api.yml # Fern API 定义环境与默认环境 │ ├── openapi.json # 由 generate_openapi.py 生成的过滤后 OpenAPI 规范 │ └── openapi-overrides.yml # OpenAPI 覆盖文件SDK 分组、示例、Agentic 事件模型 ├── docs/ # 文档站资产与页面MDX、样式、图片 ├── scripts/ # OpenAPI 生成与连接器文档生成脚本 ├── generate-local.sh # 本地一键生成脚本 ├── generators.yml # Fern 生成器配置Python/TS SDK 文档 ├── fern.config.json # Fern 核心配置 └── docs.yml # 文档站点配置导航、外观、分析说明fern/README.md中目录示意里提到的openapi/目录与definition/overrides.yml在实际仓库中对应为 fern/definition/openapi.json 与 fern/definition/openapi-overrides.yml下文均以仓库实际路径为准。二、端到端生成管线从 FastAPI 到 SDKAirweave 的文档生成不是手写维护而是一条自动化管线其完整链路记录在 fern/scripts/README.md 与 fern/generate-local.sh 中生成完整 OpenAPI 规范基于 FastAPI 应用airweave.main:app通过fastapi.openapi.utils.get_openapi导出全量路由定义见 fern/scripts/generate_openapi.py。按白名单过滤只保留api_config.py中声明允许对外暴露的端点并修复安全方案、剔除未被引用的遗留 Schema、为标签补充显示名见 fern/scripts/generate_openapi.py。输出过滤后的规范直接写入 fern/definition/openapi.json。生成连接器文档通过代码自省生成各数据源连接器的 Markdown 文档fern/scripts/update_connector_docs.py。Fern 消费规范产出 SDK 与文档站fern generate依据 fern/generators.yml 生成 Python/TypeScript SDK 与文档站点。一键生成脚本generate-local.shfern/generate-local.sh 是本地复现整条管线的入口支持从fern/目录或backend/目录通过 Poetry两种方式运行。其关键行为如下#!/bin/bash set -e # Exit on error # 1. 目录校验仅允许在 fern/ 或 backend/ 下运行 if [[ $(basename $PWD) ! fern ]] [[ $PWD ! */backend ]]; then echo ❌ Please run this script from the fern directory or via Poetry from the backend directory exit 1 fi # 2. 生成连接器文档 python scripts/update_connector_docs.py # 3. 生成过滤后的 OpenAPI 规范直接写入 definition/openapi.json cd ../backend poetry run python ../fern/scripts/generate_openapi.py cd ../fern # 4. 若本机没有 fern CLI自动全局安装 if ! command -v fern /dev/null; then echo Installing Fern CLI... npm install -g fern-api fi # 5. 执行生成器指定 public 组与版本 fern generate --group public --log-level debug --version v0.1.50 # 6. 生成文档站点 fern generate --docs使用要点前置条件仓库根目录下需要已安装 Python 依赖脚本通过poetry run调用generate_openapi.py可参考 backend/pyproject.toml网络侧依赖 Fern CLI若缺失会自动npm install -g fern-api。FERN_TOKEN脚本中做了显式检查——若未设置该环境变量会输出警告 Some features might not work因为部分 Fern 平台功能如发布到远端需要令牌本地生成 SDK 代码本身不受影响。版本钉死fern generate --version v0.1.50将生成过程固定到指定 Fern 版本避免 CLI 升级导致的兼容性漂移。产物确认脚本末尾通过ls -la definition/打印生成结果方便核对openapi.json是否已更新。三、OpenAPI 的白名单机制只暴露该暴露的端点Airweave 的全量 FastAPI 应用包含健康检查、API Key 管理、Chat、Cursor 开发端点、DAG 管理等众多内部/管理路由。若不加筛选地导入 FernSDK 与公开文档会混入大量不该对外暴露的接口。因此仓库通过两层机制控制 API 面。第一层api_config.py端点白名单fern/scripts/api_config.py 定义了INCLUDED_ENDPOINTS字典将公开 SDK 限制在四个 API 组API 组暴露的端点方法SourcesGET /sources、GET /sources/{short_name}CollectionsGET/POST /collections、GET/PATCH/DELETE /collections/{readable_id}、GET/POST /collections/{readable_id}/search、POST .../search/instant、POST .../search/classic、POST .../search/agentic、POST .../search/agentic/streamSource ConnectionsGET/POST /source-connections、GET/PATCH/DELETE /source-connections/{source_connection_id}、POST .../run、GET .../jobs、POST .../jobs/{job_id}/cancelWebhooksGET /webhooks/messages、GET /webhooks/messages/{message_id}、GET/POST /webhooks/subscriptions、GET/PATCH/DELETE /webhooks/subscriptions/{subscription_id}、POST .../recoveris_included_endpoint(path, method)通过归一化路径处理尾部斜杠差异匹配字典键并校验 HTTP 方法是否在白名单内见 fern/scripts/api_config.py。第二层generate_openapi.py的规范级处理fern/scripts/generate_openapi.py 在拿到 FastAPI 全量规范后依次执行四个变换filter_paths按上述白名单逐路径、逐方法过滤只保留允许的 Operation见 fern/scripts/generate_openapi.py。fix_security_scheme将鉴权方案统一替换为ApiKeyAuthheader 中传x-api-key并从每个 Operation 中删除Authorization、x-api-key、X-API-Key、X-Organization-ID等参数避免与 security scheme 重复导致生成 SDK 报 duplicate parameter 错误见 fern/scripts/generate_openapi.py。这意味着公开 SDK 的鉴权方式被收敛为单一 API Key。remove_unreferenced_schemas迭代删除未被任何端点或其他 Schema 引用的遗留模型例如旧版RetrievalStrategy中的neural枚举防止过期类型泄漏进 SDK见 fern/scripts/generate_openapi.py。add_tag_display_names为collections、source-connections、sources、webhooks四个标签补充x-display-name让文档与 SDK 分组更友好见 fern/scripts/generate_openapi.py。此外脚本还会在规范中注入两个 Server 定义https://api.airweave.aiProduction与http://localhost:8001Local并在info.description中追加 API 分组说明见 fern/scripts/generate_openapi.py。Fern API 定义definition/api.ymlfern/definition/api.yml 与上述 Server 定义呼应声明了 Fern 侧的环境信息name: api environments: Production: docs: The production environment that points to the production API. url: https://api.airweave.ai Local: docs: The local environment that points to your local API. url: http://localhost:8001 default-environment: Production即 SDK 默认指向生产环境https://api.airweave.ai同时保留本地http://localhost:8001便于联调。四、Overrides覆盖规范、定制 SDK 形态fern/definition/openapi-overrides.yml 是对openapi.json的补充定制主要解决三类问题。1. 移除生成的示例噪音对SourceConnectionCreate、SourceConnectionUpdate两个 Schema 显式将examples置为null避免自动生成的示例干扰 SDK 文档。2. 定义 Agentic 搜索的流式事件模型Airweave 的 Agentic 搜索POST /collections/{readable_id}/search/agentic/stream以 SSE 流式返回事件Overrides 为它定义了完整的判别联合discriminated unionAgenticSearchEvent事件类型started、thinking、tool_call、reranking、done、error通过propertyName: type判别。thinking事件携带 LLM 扩展推理文本thinking、对话文本text、耗时duration_ms与诊断信息iteration、prompt_tokens、completion_tokens。tool_call事件携带tool_name枚举search、read、add_to_results、remove_from_results、count、get_children、get_siblings、get_parent、review_results、return_results_to_user以及按工具区分的统计结构SearchToolStats/ReadToolStats/CollectToolStats/CountToolStats/NavigateToolStats/ReviewToolStats/FinishToolStats/ErrorToolStats。reranking事件记录重排前后数量、所用模型与相关性得分区间。done事件返回完整结果集与总迭代次数、已见/已读/已收集实体 ID、是否触发最大迭代、LLM 重试次数、停滞提示次数及 Token 统计。error事件携带错误消息与耗时。同时为流式端点声明x-fern-streaming: format: sse让生成的 SDK 正确暴露流式调用形态。3. 定制 SDK 分组、方法名与示例通过x-fern-sdk-group-name与x-fern-sdk-method-name将搜索端点归入collections.search分组并命名为instant、classic、agentic、stream_agentic同时用x-fern-examples提供包含 Notion 页面、Slack 消息等真实形态的请求/响应示例这些示例会被直接嵌入生成的 SDK 文档与在线文档极大提升可读性。与 fern/README.md Overrides 一节的表述对应健康检查、API Key 管理、Chat、Cursor 开发端点、DAG 管理端点等内部路由正是通过上文api_config.py白名单 generate_openapi.py过滤从公开文档与 SDK 中剔除的。五、生成器配置Python 与 TypeScript 双 SDKfern/generators.yml 是 SDK 产物的配方表它先声明规范来源api: specs: - openapi: ./definition/openapi.json overrides: ./definition/openapi-overrides.yml然后在public组中定义两个生成器Python SDK发布到 PyPI- name: fernapi/fern-python-sdk version: 4.30.2 output: location: pypi package-name: airweave-sdk token: ${PYPI_TOKEN} github: repository: airweave-ai/python-sdk config: client_class_name: AirweaveSDKTypeScript SDK发布到 npm- name: fernapi/fern-typescript-node-sdk version: 3.3.3 output: location: npm package-name: airweave/sdk token: ${NPM_TOKEN} github: repository: airweave-ai/typescript-sdk config: namespaceExport: AirweaveSDK要点解读发布目标Python 包名为airweave-sdk客户端类名为AirweaveSDKnpm 包名为airweave/sdk使用namespaceExport: AirweaveSDK以命名空间方式导出。凭据注入发布 token 通过环境变量${PYPI_TOKEN}、${NPM_TOKEN}注入不在仓库中保存任何密钥。版本管理Python 生成器 4.30.2、TS 生成器 3.3.3 均为固定版本保证可复现性SDK 源码仓库由 Fern 自动推送至airweave-ai/python-sdk与airweave-ai/typescript-sdk。公开 API 引用fern/docs.yml 的 API Reference 布局中为代码片段指定了语言映射python: airweave-sdk与typescript: airweave/sdk与生成器配置一一对应。六、文档站点配置docs.yml与fern.config.jsonfern.config.json核心身份fern/fern.config.json 内容极简却定义了 Fern 工作区的身份{ organization: airweave, version: 0.83.0 }organization对应 Fern 组织与 fern/generators.yml 中 SDK 仓库归属一致version为配置格式版本。docs.yml站点导航、API 引用与外观fern/docs.yml 是文档站的完整蓝图核心内容包括实例与域名发布到airweave.docs.buildwithfern.com并绑定自定义域名docs.airweave.ai开启 Edit this page 指向 GitHub 仓库airweave-ai/airweave的main分支。分析与统计接入 PostHog含 api-key 与 EU 端点searchbar-placement: header提供站内搜索。布局page-width: full、content-width: 1000px。导航结构包含 DocsWelcome、Quickstart、Concepts、Search、MCP Server、CLI、Agent Skills、Connect、Webhooks、Add New Connector、Rate Limits、Framework IntegrationsLlamaIndex、Vercel AI SDK、Google Antigravity、Pipedream、Sim、AuthenticationAuth Providers、OAuth、Direct Token Injection以及数十个 Connectors 页面页面文件均为docs/pages/下的 MDX。API Reference 布局按 Collections、Source Connections、Sources、Webhooks 四个 section 组织端点其中 Collections 下完整列出 instant/classic/agentic/agentic stream 四个搜索端点。品牌外观主题色#4199D3、明暗双色背景#FAFCFE/#060606、Logofern/docs/assets/dark_logo_word.svg 与 fern/docs/assets/light_logo_word.svg、favicon 与自定义 CSS/JSfern/docs/styles.css、fern/docs/assets/custom-connectors.js。七、连接器文档的自动化生成除 OpenAPI 管线外fern/scripts/还包含一套连接器文档生成体系fern/scripts/update_connector_docs.py 作为入口委托给 fern/scripts/update_connector_docs/main.py通过parsers/source、config、auth、entity 解析器与generators/mdx_generator.py将monke/bongos/中连接器实现与monke/configs/下 YAML 配置如 monke/configs/notion.yaml 之类转译为各连接器的main.mdx文档页面再由docs.yml挂载到站点导航中。这样连接器文档与实现代码保持同步避免手写文档滞后。八、小结与本地实操路径Fern 模块让 Airweave 对外 API 的维护形成闭环FastAPI 路由 →api_config.py白名单 →generate_openapi.py变换 →openapi.json→ Fern 生成器 → Python/TS SDK 与文档站。对开发者而言最直接的收益是在本地复现整套生成流程在仓库backend/目录下执行poetry run python ../fern/scripts/generate_openapi.py可单独刷新 OpenAPI 规范完整执行则运行./generate-local.sh需在fern/或backend/目录。若想调整对外 API 面修改 fern/scripts/api_config.py 的INCLUDED_ENDPOINTS后重新生成即可SDK 形态定制则通过 fern/definition/openapi-overrides.yml 的x-fern-*扩展实现。SDK 消费方视角Python 侧安装airweave-sdk并使用AirweaveSDK客户端默认指向https://api.airweave.ai以x-api-key头传递 API Key 完成鉴权本地联调可切换至http://localhost:8001。【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweave创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Airweave 的 Fern 模块：API 文档与多语言 SDK 的自动化生成管线
Airweave 的 Fern 模块API 文档与多语言 SDK 的自动化生成管线【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweave导读本文聚焦 Airweave 开源仓库中的fern/目录完整拆解该项目如何借助 Fern 平台从 FastAPI 应用自动导出经过筛选与定制的 OpenAPI 规范再一键生成 Pythonairweave-sdk与 TypeScriptairweave/sdk两套官方 SDK 以及在线 API 文档。读完本文你将掌握 Airweave 文档管线中每条配置文件的真实作用、本地一键生成命令的执行链路以及如何通过 Overrides 与白名单机制控制对外暴露的 API 面。一、fern/目录在 Airweave 中的定位Airweave 是一个面向 AI Agent 的开源上下文检索层context retrieval layer其核心能力集中在backend/airweave/api下的 FastAPI 路由见 backend/airweave/api。而fern/目录是这套服务对外产品化的关键一环它承载了 Airweave 官方 API 文档的定义、站点配置以及 SDK 的生成配置。按照 fern/README.md 的描述该目录的职责是This directory contains the Fern API definition and configuration for Airweaves API documentation and SDK generation.即为 Airweave 的 API 文档与 SDK 生成提供 Fern 侧的 API 定义与配置。它是连接后端实现与开发者体验之间的装配车间。目录结构总览fern/ ├── definition/ # API 定义文件含 Overrides 与生成的 OpenAPI │ ├── api.yml # Fern API 定义环境与默认环境 │ ├── openapi.json # 由 generate_openapi.py 生成的过滤后 OpenAPI 规范 │ └── openapi-overrides.yml # OpenAPI 覆盖文件SDK 分组、示例、Agentic 事件模型 ├── docs/ # 文档站资产与页面MDX、样式、图片 ├── scripts/ # OpenAPI 生成与连接器文档生成脚本 ├── generate-local.sh # 本地一键生成脚本 ├── generators.yml # Fern 生成器配置Python/TS SDK 文档 ├── fern.config.json # Fern 核心配置 └── docs.yml # 文档站点配置导航、外观、分析说明fern/README.md中目录示意里提到的openapi/目录与definition/overrides.yml在实际仓库中对应为 fern/definition/openapi.json 与 fern/definition/openapi-overrides.yml下文均以仓库实际路径为准。二、端到端生成管线从 FastAPI 到 SDKAirweave 的文档生成不是手写维护而是一条自动化管线其完整链路记录在 fern/scripts/README.md 与 fern/generate-local.sh 中生成完整 OpenAPI 规范基于 FastAPI 应用airweave.main:app通过fastapi.openapi.utils.get_openapi导出全量路由定义见 fern/scripts/generate_openapi.py。按白名单过滤只保留api_config.py中声明允许对外暴露的端点并修复安全方案、剔除未被引用的遗留 Schema、为标签补充显示名见 fern/scripts/generate_openapi.py。输出过滤后的规范直接写入 fern/definition/openapi.json。生成连接器文档通过代码自省生成各数据源连接器的 Markdown 文档fern/scripts/update_connector_docs.py。Fern 消费规范产出 SDK 与文档站fern generate依据 fern/generators.yml 生成 Python/TypeScript SDK 与文档站点。一键生成脚本generate-local.shfern/generate-local.sh 是本地复现整条管线的入口支持从fern/目录或backend/目录通过 Poetry两种方式运行。其关键行为如下#!/bin/bash set -e # Exit on error # 1. 目录校验仅允许在 fern/ 或 backend/ 下运行 if [[ $(basename $PWD) ! fern ]] [[ $PWD ! */backend ]]; then echo ❌ Please run this script from the fern directory or via Poetry from the backend directory exit 1 fi # 2. 生成连接器文档 python scripts/update_connector_docs.py # 3. 生成过滤后的 OpenAPI 规范直接写入 definition/openapi.json cd ../backend poetry run python ../fern/scripts/generate_openapi.py cd ../fern # 4. 若本机没有 fern CLI自动全局安装 if ! command -v fern /dev/null; then echo Installing Fern CLI... npm install -g fern-api fi # 5. 执行生成器指定 public 组与版本 fern generate --group public --log-level debug --version v0.1.50 # 6. 生成文档站点 fern generate --docs使用要点前置条件仓库根目录下需要已安装 Python 依赖脚本通过poetry run调用generate_openapi.py可参考 backend/pyproject.toml网络侧依赖 Fern CLI若缺失会自动npm install -g fern-api。FERN_TOKEN脚本中做了显式检查——若未设置该环境变量会输出警告 Some features might not work因为部分 Fern 平台功能如发布到远端需要令牌本地生成 SDK 代码本身不受影响。版本钉死fern generate --version v0.1.50将生成过程固定到指定 Fern 版本避免 CLI 升级导致的兼容性漂移。产物确认脚本末尾通过ls -la definition/打印生成结果方便核对openapi.json是否已更新。三、OpenAPI 的白名单机制只暴露该暴露的端点Airweave 的全量 FastAPI 应用包含健康检查、API Key 管理、Chat、Cursor 开发端点、DAG 管理等众多内部/管理路由。若不加筛选地导入 FernSDK 与公开文档会混入大量不该对外暴露的接口。因此仓库通过两层机制控制 API 面。第一层api_config.py端点白名单fern/scripts/api_config.py 定义了INCLUDED_ENDPOINTS字典将公开 SDK 限制在四个 API 组API 组暴露的端点方法SourcesGET /sources、GET /sources/{short_name}CollectionsGET/POST /collections、GET/PATCH/DELETE /collections/{readable_id}、GET/POST /collections/{readable_id}/search、POST .../search/instant、POST .../search/classic、POST .../search/agentic、POST .../search/agentic/streamSource ConnectionsGET/POST /source-connections、GET/PATCH/DELETE /source-connections/{source_connection_id}、POST .../run、GET .../jobs、POST .../jobs/{job_id}/cancelWebhooksGET /webhooks/messages、GET /webhooks/messages/{message_id}、GET/POST /webhooks/subscriptions、GET/PATCH/DELETE /webhooks/subscriptions/{subscription_id}、POST .../recoveris_included_endpoint(path, method)通过归一化路径处理尾部斜杠差异匹配字典键并校验 HTTP 方法是否在白名单内见 fern/scripts/api_config.py。第二层generate_openapi.py的规范级处理fern/scripts/generate_openapi.py 在拿到 FastAPI 全量规范后依次执行四个变换filter_paths按上述白名单逐路径、逐方法过滤只保留允许的 Operation见 fern/scripts/generate_openapi.py。fix_security_scheme将鉴权方案统一替换为ApiKeyAuthheader 中传x-api-key并从每个 Operation 中删除Authorization、x-api-key、X-API-Key、X-Organization-ID等参数避免与 security scheme 重复导致生成 SDK 报 duplicate parameter 错误见 fern/scripts/generate_openapi.py。这意味着公开 SDK 的鉴权方式被收敛为单一 API Key。remove_unreferenced_schemas迭代删除未被任何端点或其他 Schema 引用的遗留模型例如旧版RetrievalStrategy中的neural枚举防止过期类型泄漏进 SDK见 fern/scripts/generate_openapi.py。add_tag_display_names为collections、source-connections、sources、webhooks四个标签补充x-display-name让文档与 SDK 分组更友好见 fern/scripts/generate_openapi.py。此外脚本还会在规范中注入两个 Server 定义https://api.airweave.aiProduction与http://localhost:8001Local并在info.description中追加 API 分组说明见 fern/scripts/generate_openapi.py。Fern API 定义definition/api.ymlfern/definition/api.yml 与上述 Server 定义呼应声明了 Fern 侧的环境信息name: api environments: Production: docs: The production environment that points to the production API. url: https://api.airweave.ai Local: docs: The local environment that points to your local API. url: http://localhost:8001 default-environment: Production即 SDK 默认指向生产环境https://api.airweave.ai同时保留本地http://localhost:8001便于联调。四、Overrides覆盖规范、定制 SDK 形态fern/definition/openapi-overrides.yml 是对openapi.json的补充定制主要解决三类问题。1. 移除生成的示例噪音对SourceConnectionCreate、SourceConnectionUpdate两个 Schema 显式将examples置为null避免自动生成的示例干扰 SDK 文档。2. 定义 Agentic 搜索的流式事件模型Airweave 的 Agentic 搜索POST /collections/{readable_id}/search/agentic/stream以 SSE 流式返回事件Overrides 为它定义了完整的判别联合discriminated unionAgenticSearchEvent事件类型started、thinking、tool_call、reranking、done、error通过propertyName: type判别。thinking事件携带 LLM 扩展推理文本thinking、对话文本text、耗时duration_ms与诊断信息iteration、prompt_tokens、completion_tokens。tool_call事件携带tool_name枚举search、read、add_to_results、remove_from_results、count、get_children、get_siblings、get_parent、review_results、return_results_to_user以及按工具区分的统计结构SearchToolStats/ReadToolStats/CollectToolStats/CountToolStats/NavigateToolStats/ReviewToolStats/FinishToolStats/ErrorToolStats。reranking事件记录重排前后数量、所用模型与相关性得分区间。done事件返回完整结果集与总迭代次数、已见/已读/已收集实体 ID、是否触发最大迭代、LLM 重试次数、停滞提示次数及 Token 统计。error事件携带错误消息与耗时。同时为流式端点声明x-fern-streaming: format: sse让生成的 SDK 正确暴露流式调用形态。3. 定制 SDK 分组、方法名与示例通过x-fern-sdk-group-name与x-fern-sdk-method-name将搜索端点归入collections.search分组并命名为instant、classic、agentic、stream_agentic同时用x-fern-examples提供包含 Notion 页面、Slack 消息等真实形态的请求/响应示例这些示例会被直接嵌入生成的 SDK 文档与在线文档极大提升可读性。与 fern/README.md Overrides 一节的表述对应健康检查、API Key 管理、Chat、Cursor 开发端点、DAG 管理端点等内部路由正是通过上文api_config.py白名单 generate_openapi.py过滤从公开文档与 SDK 中剔除的。五、生成器配置Python 与 TypeScript 双 SDKfern/generators.yml 是 SDK 产物的配方表它先声明规范来源api: specs: - openapi: ./definition/openapi.json overrides: ./definition/openapi-overrides.yml然后在public组中定义两个生成器Python SDK发布到 PyPI- name: fernapi/fern-python-sdk version: 4.30.2 output: location: pypi package-name: airweave-sdk token: ${PYPI_TOKEN} github: repository: airweave-ai/python-sdk config: client_class_name: AirweaveSDKTypeScript SDK发布到 npm- name: fernapi/fern-typescript-node-sdk version: 3.3.3 output: location: npm package-name: airweave/sdk token: ${NPM_TOKEN} github: repository: airweave-ai/typescript-sdk config: namespaceExport: AirweaveSDK要点解读发布目标Python 包名为airweave-sdk客户端类名为AirweaveSDKnpm 包名为airweave/sdk使用namespaceExport: AirweaveSDK以命名空间方式导出。凭据注入发布 token 通过环境变量${PYPI_TOKEN}、${NPM_TOKEN}注入不在仓库中保存任何密钥。版本管理Python 生成器 4.30.2、TS 生成器 3.3.3 均为固定版本保证可复现性SDK 源码仓库由 Fern 自动推送至airweave-ai/python-sdk与airweave-ai/typescript-sdk。公开 API 引用fern/docs.yml 的 API Reference 布局中为代码片段指定了语言映射python: airweave-sdk与typescript: airweave/sdk与生成器配置一一对应。六、文档站点配置docs.yml与fern.config.jsonfern.config.json核心身份fern/fern.config.json 内容极简却定义了 Fern 工作区的身份{ organization: airweave, version: 0.83.0 }organization对应 Fern 组织与 fern/generators.yml 中 SDK 仓库归属一致version为配置格式版本。docs.yml站点导航、API 引用与外观fern/docs.yml 是文档站的完整蓝图核心内容包括实例与域名发布到airweave.docs.buildwithfern.com并绑定自定义域名docs.airweave.ai开启 Edit this page 指向 GitHub 仓库airweave-ai/airweave的main分支。分析与统计接入 PostHog含 api-key 与 EU 端点searchbar-placement: header提供站内搜索。布局page-width: full、content-width: 1000px。导航结构包含 DocsWelcome、Quickstart、Concepts、Search、MCP Server、CLI、Agent Skills、Connect、Webhooks、Add New Connector、Rate Limits、Framework IntegrationsLlamaIndex、Vercel AI SDK、Google Antigravity、Pipedream、Sim、AuthenticationAuth Providers、OAuth、Direct Token Injection以及数十个 Connectors 页面页面文件均为docs/pages/下的 MDX。API Reference 布局按 Collections、Source Connections、Sources、Webhooks 四个 section 组织端点其中 Collections 下完整列出 instant/classic/agentic/agentic stream 四个搜索端点。品牌外观主题色#4199D3、明暗双色背景#FAFCFE/#060606、Logofern/docs/assets/dark_logo_word.svg 与 fern/docs/assets/light_logo_word.svg、favicon 与自定义 CSS/JSfern/docs/styles.css、fern/docs/assets/custom-connectors.js。七、连接器文档的自动化生成除 OpenAPI 管线外fern/scripts/还包含一套连接器文档生成体系fern/scripts/update_connector_docs.py 作为入口委托给 fern/scripts/update_connector_docs/main.py通过parsers/source、config、auth、entity 解析器与generators/mdx_generator.py将monke/bongos/中连接器实现与monke/configs/下 YAML 配置如 monke/configs/notion.yaml 之类转译为各连接器的main.mdx文档页面再由docs.yml挂载到站点导航中。这样连接器文档与实现代码保持同步避免手写文档滞后。八、小结与本地实操路径Fern 模块让 Airweave 对外 API 的维护形成闭环FastAPI 路由 →api_config.py白名单 →generate_openapi.py变换 →openapi.json→ Fern 生成器 → Python/TS SDK 与文档站。对开发者而言最直接的收益是在本地复现整套生成流程在仓库backend/目录下执行poetry run python ../fern/scripts/generate_openapi.py可单独刷新 OpenAPI 规范完整执行则运行./generate-local.sh需在fern/或backend/目录。若想调整对外 API 面修改 fern/scripts/api_config.py 的INCLUDED_ENDPOINTS后重新生成即可SDK 形态定制则通过 fern/definition/openapi-overrides.yml 的x-fern-*扩展实现。SDK 消费方视角Python 侧安装airweave-sdk并使用AirweaveSDK客户端默认指向https://api.airweave.ai以x-api-key头传递 API Key 完成鉴权本地联调可切换至http://localhost:8001。【免费下载链接】airweaveOpen-source context retrieval layer for AI agents项目地址: https://gitcode.com/GitHub_Trending/ai/airweave创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考