🎯 開發動機與解決痛點
在現代企業環境中,知識分散在各種應用程式、資料庫和文檔儲存系統中,讓 AI 代理無法有效存取和搜尋這些寶貴資訊。Airweave 正是為了解決這個核心問題而誕生的創新平台。
核心痛點:
資訊孤島問題 :知識散布在 GitHub、Notion、Google Drive、Slack 等不同平台
搜尋標準化挑戰 :每個應用程式都有不同的搜尋介面和 API
AI 代理整合困難 :缺乏統一的語義搜尋介面讓 AI 存取企業知識
資料同步複雜性 :手動維護多個資料源的同步耗時且容易出錯
權限管理分散 :每個系統都有不同的權限控制機制
Airweave 透過建立統一的搜尋介面,將任何應用程式轉換為可搜尋的知識庫,並透過 REST API 和 Model Context Protocol (MCP) 讓 AI 代理能夠無縫存取企業的全部知識資產。這個解決方案特別適合需要 AI 驅動知識管理的現代企業和開發團隊。
🛠️ 技術框架與設計模式
🔧 FastAPI 後端架構
採用現代異步 Python 框架,支援自動 API 文檔生成、類型檢查,並具備出色的效能表現,特別適合 AI 應用的高並發需求。
⚛️ React + TypeScript 前端
使用 React 18 與 TypeScript 建構現代化用戶介面,搭配 ShadCN/UI 元件庫提供一致的設計體驗,並透過 Zustand 進行狀態管理。
🗄️ 雙資料庫架構
PostgreSQL 儲存元資料與關聯資料,Qdrant 向量資料庫處理語義搜尋,實現結構化與非結構化資料的完美結合。
🔄 Temporal 工作流引擎
採用 Temporal 處理複雜的資料同步工作流,確保可靠性、可觀測性和錯誤復原能力。
🤖 OpenAI + 本地嵌入模型
支援 OpenAI 和本地 text2vec 模型,提供靈活的語義搜尋選擇,平衡成本與效能需求。
🐳 Docker 容器化部署
完整的 Docker Compose 開發環境,支援一鍵啟動所有服務,簡化開發和部署流程。
核心設計模式
🏗️ 抽象工廠模式 (Abstract Factory)
透過 platform/sources/ 目录中的基類實作,每個資料源都繼承 BaseSource,提供統一的介面來處理不同類型的外部資料來源。
🎯 策略模式 (Strategy Pattern)
在轉換器系統中使用,如 optimized_file_chunker.py 根據檔案類型選擇不同的處理策略,確保各種文檔格式都能被正確處理。
📝 觀察者模式 (Observer Pattern)
前端使用事件系統監聽 Collection 變更,確保用戶介面與後端狀態同步,提供即時的用戶體驗。
🔧 後端同步協調器實作
class SyncOrchestrator :
"""協調資料同步的核心類別,採用拉取式並發控制"""
def __init__ (self, entity_processor, worker_pool, sync_context):
self.entity_processor = entity_processor
self.worker_pool = worker_pool
self.sync_context = sync_context
self.stream_buffer_size = 100
async def _process_entities (self):
"""使用拉取式並發控制處理實體資料"""
async with AsyncSourceStream(
self.sync_context.source.generate_entities(),
queue_size=self.stream_buffer_size
) as stream:
async for entity in stream.get_entities():
if getattr(entity, "should_skip" , False ):
await self.sync_context.progress.increment("skipped" )
continue
task = await self.worker_pool.submit(
self.entity_processor.process,
entity=entity,
source_node=source_node,
sync_context=self.sync_context
)
這個實作展示了如何使用非同步流處理大量資料,同時透過工作池控制並發數量,避免系統過載。
🎨 前端狀態管理架構
import { create } from 'zustand' ;
interface CollectionsState {
collections: Collection[];
isLoading: boolean ;
sourceConnections: Record<string , SourceConnection[]>;
fetchCollections: (forceRefresh?: boolean ) => Promise<Collection[]>;
subscribeToEvents: () => () => void ;
clearCollections: () => void ;
}
export const useCollectionsStore = create<CollectionsState>((set, get) => ({
collections: [],
isLoading: false ,
sourceConnections: {},
fetchCollections : async (forceRefresh = false ) => {
const { collections, isLoading } = get();
if (collections.length > 0 && !forceRefresh) {
console.log("🔍 使用快取資料,略過 API 呼叫" );
return collections;
}
set({ isLoading: true , error: null });
const response = await apiClient.get('/collections' );
}
}));
這個狀態管理實作透過智能快取減少不必要的 API 呼叫,並提供事件訂閱機制確保資料一致性。
⚡ 智能檔案分塊處理
async def _try_chunk_size (
file: FileEntity, text_content: str , chunk_size: int
) -> tuple[bool , list[ChunkEntity]]:
"""嘗試特定大小的分塊,驗證是否符合 OpenAI 限制"""
final_chunk_texts = await _chunk_text_adaptive(text_content, chunk_size)
parent = FileParentClass(**file.model_dump())
all_chunks_fit = True
test_chunks = []
for i, chunk_text in enumerate(final_chunk_texts):
chunk = _create_chunk_entity(file, parent, chunk_text, i)
actual_size = calculate_entity_token_size(chunk)
if actual_size > OPENAI_TOKEN_LIMIT:
logger.warning(f"分塊 {i + 1} 過大: {actual_size} tokens" )
all_chunks_fit = False
break
else :
test_chunks.append(chunk)
return all_chunks_fit, [parent] + test_chunks if all_chunks_fit else []
這個轉換器確保所有文檔分塊都符合 OpenAI 的 token 限制,透過動態調整分塊大小來優化處理效果。
💡 應用情境
📱 企業知識管理平台
大型企業可以將 Airweave 部署為內部知識管理中心,整合 Confluence、SharePoint、內部 Wiki 等系統,讓員工透過自然語言查詢快速找到所需資訊,並支援 AI 助理進行智能問答。
🤖 AI 代理開發平台
開發者可以使用 Airweave 為 AI 代理提供豐富的上下文資訊,透過 MCP (Model Context Protocol) 讓 Claude、GPT 等 AI 模型能夠存取和搜尋特定領域的知識庫,提升回答品質和準確性。
🔍 多源資料分析系統
研究機構和數據分析團隊可以整合來自不同資料庫、API 和文檔系統的資訊,建立統一的搜尋介面,支援跨源的語義搜尋和資料探索,加速研究和分析工作。
📚 個人知識助理
個人用戶可以連接 Notion、Google Drive、GitHub 等個人工作平台,建立專屬的知識搜尋系統,讓 AI 助理能夠理解和搜尋個人的筆記、專案和文檔。
🏢 白標客製化解決方案
SaaS 服務商可以使用 Airweave 的白標功能,為客戶提供客製化的知識搜尋解決方案,支援自訂域名、品牌樣式和特定功能配置。
🏗️ 軟體架構圖
用戶介面
React + TypeScript
AI 代理
MCP + REST API
FastAPI 後端服務
異步 Python + 認證中介軟體
同步引擎
Temporal 工作流
搜尋引擎
語義 + 向量搜尋
GitHub
Notion
Google Drive
PostgreSQL
Qdrant 向量庫
OpenAI 嵌入
本地 Text2Vec
圖例:
前端介面
後端服務
外部資料源
資料庫層
AI 模型
Airweave 採用分層式架構,透過統一的 API 閘道整合多種資料源,並使用向量資料庫實現高效的語義搜尋
❓ 常見問題 Q&A
Q1: Airweave 如何確保資料安全性和隱私保護?
🔒 多層安全機制
組織隔離: 採用多租戶架構,每個組織的資料完全隔離,確保資料不會洩露給其他用戶。
API 金鑰認證: 支援基於 API 金鑰的認證機制,可設定不同權限等級的存取控制。
OAuth2 整合: 與 Auth0 整合提供企業級身份驗證,支援 SSO 和多因素認證。
此外,系統還支援本地部署,敏感資料可完全留在企業內部環境中。
Q2: 支援哪些類型的資料源,如何新增自訂資料源?
📦 內建資料源支援
Airweave 目前支援超過 25 種資料源,包括:
開發工具: GitHub、GitLab、Bitbucket
協作平台: Notion、Confluence、Monday.com
雲端儲存: Google Drive、OneDrive、Dropbox
通訊工具: Slack、Gmail、Outlook
專案管理: Jira、Linear、Asana
資料庫: PostgreSQL、MySQL、SQLite
自訂資料源開發: 透過繼承 BaseSource 類別,開發者可以輕鬆新增自訂資料源。系統提供完整的開發文檔和範例程式碼。
Q3: 系統的擴展性如何?能否處理大規模企業的資料量?
⚡ 高效能架構設計
異步處理: 採用 FastAPI 的異步架構,支援高並發請求處理,單一實例可處理數千個同時連線。
工作流引擎: 使用 Temporal 處理大規模資料同步,支援分散式處理和自動故障恢復。
向量資料庫優化: Qdrant 向量資料庫針對大規模語義搜尋進行優化,支援數百萬向量的高效查詢。
系統採用微服務架構設計,可透過 Kubernetes 進行水平擴展,滿足企業級應用需求。
Q4: 如何與現有的 AI 工具和工作流程整合?
🤖 AI 整合方案
MCP 協議支援: 支援 Model Context Protocol,可直接與 Claude、GPT 等 AI 模型整合。
RESTful API: 提供完整的 REST API,可輕鬆整合到現有的應用程式和工作流程中。
SDK 支援: 提供 Python 和 TypeScript SDK,簡化開發者的整合工作。
系統還支援 Webhook 通知和即時事件推送,確保 AI 代理能及時獲得最新的資料更新。
🔮 未來展望
Airweave 持續演進,致力於成為 AI 時代最重要的知識基礎設施。以下是我們規劃中的重要功能和改進:
🚀 Redis 工作佇列
實作基於 Redis 的分散式工作佇列系統,支援大規模資料同步任務的高效處理和負載平衡。
🔄 Webhook 事件驅動同步
支援 Webhook 觸發的即時同步機制,讓資料更新能夠即時反映到搜尋結果中,提升資料新鮮度。
☸️ Kubernetes 原生支援
提供 Helm Charts 和 Kubernetes Operator,簡化在容器化環境中的部署和管理流程。
🔌 更多資料源整合
持續擴展資料源支援,包括 Salesforce、HubSpot、Zendesk 等企業級 SaaS 平台。
🧠 進階 AI 功能
整合更多 AI 模型,支援摘要生成、自動標記、智能推薦等進階功能。
📊 分析和洞察面板
提供使用情況分析、搜尋熱點、資料品質評估等企業級分析功能。