
AIRI 的 xsAI 包選型指南細粒度 xsai/* 包與 xsai 傘包如何取舍【免費下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI 的 LLM、語音、工具調(diào)用等能力構(gòu)建在 xsAI 這套 OpenAI 兼容運行時之上而選對包決定了安裝體積、導入面與維護成本。本文基于倉庫內(nèi)的選型參考文檔 .agents/skills/xsai/references/package-selection.md 展開完整繼承其中的通用規(guī)則、逐包推薦與導入建議并結(jié)合同倉庫各包的package.json、pnpm catalog 與實際源碼調(diào)用給出在 AIRI 這類多包前端工程中可復制、可驗證的選型方法。核心原則優(yōu)先最小包傘包是例外參考文檔給出的第一條通用規(guī)則General rule是優(yōu)先選擇能解決問題的最小包Prefer the smallest package that solves the task。只有當用戶同時需要多種功能或希望保持單一導入面single import surface時才推薦傘包umbrellaxsai。這條規(guī)則在倉庫頂層的技能說明 .agents/skills/xsai/SKILL.md 中被再次強化默認工作流要求“先檢查現(xiàn)有倉庫的依賴與導入風格保留xsai或細粒度xsai/*的既有寫法”“當用戶以 bundle 或安裝體積為優(yōu)化目標時明確優(yōu)先xsai/generate-text這類細粒度包而非xsai”。換句話說在 AIRI 生態(tài)的語境里細粒度包是默認解傘包是需要理由才啟用的備選解。逐包推薦xsAI 包家族一覽參考文檔列出了 10 個細粒度包加 1 個傘包。下表完整繼承原推薦清單并結(jié)合對倉庫內(nèi)所有packages/、apps/、integrations/、services/下package.json的掃描補充了每個包在 AIRI 中的實際引用情況引用次數(shù)為依賴聲明行數(shù)統(tǒng)計可據(jù)此判斷哪些包是工程主力包名官方推薦用途引自參考文檔AIRI 倉庫中的引用情況xsai/generate-text最簡單的單程unary文本生成10 處覆蓋面最廣的主力包xsai/stream-text流式文本或工具事件6 處如 packages/core-agent/src/runtime/llm-service.tsxsai/generate-object帶校驗的結(jié)構(gòu)化輸出當前掃描范圍內(nèi)未發(fā)現(xiàn)直接依賴聲明xsai/stream-object增量式結(jié)構(gòu)化輸出當前掃描范圍內(nèi)未發(fā)現(xiàn)直接依賴聲明xsai/tool工具定義與原始 JSON Schema 工具7 處tool()與rawTool()均有使用xsai/embed文本嵌入embeddings2 處xsai/generate-image圖像生成當前掃描范圍內(nèi)未發(fā)現(xiàn)直接依賴聲明xsai/generate-speech文本轉(zhuǎn)語音TTS8 處如 packages/stage-ui/src/stores/modules/speech.tsxsai/generate-transcription單程語音轉(zhuǎn)寫2 處xsai/stream-transcription流式語音轉(zhuǎn)寫6 處如 packages/stage-ui/src/libs/providers/stream-transcription/index.tsxsai傘包重新導出以上所有包倉庫內(nèi)各package.json均未直接依賴傘包從上表可以得到一個直接結(jié)論AIRI 是一個徹底的“細粒度派”倉庫——沒有任何一個子包聲明了對傘包xsai的依賴每個包只引入自己真正用到的 API。這正是參考文檔“優(yōu)先最小包”規(guī)則在一個大型 monorepo 中被完整執(zhí)行的樣本。此外從倉庫結(jié)構(gòu)看AIRI 實際使用的依賴面比參考文檔清單更細還包含若干支撐型包xsai/shared-chat11 處共享的Message、Tool、Usage等類型與stepCountAtLeast等停止條件工具xsai/model5 處如listModels模型列表查詢見 packages/stage-ui/src/stores/ai/chat-llm/llm.tsxsai/shared、xsai/utils-chat各 56 處通用請求選項與聊天工具函數(shù)。參考文檔的清單聚焦“功能入口包”而支撐型包通常作為類型依賴伴隨出現(xiàn)選型時若只需某一功能入口功能包是決策主體支撐包隨類型引用自動進入依賴圖。版本統(tǒng)一pnpm catalog 鎖定全部 xsai/* 版本細粒度包數(shù)量較多時版本漂移是常見風險。AIRI 用 pnpm workspace 的 catalog 機制規(guī)避了這個問題pnpm-workspace.yaml 將全部xsai/*包統(tǒng)一釘在0.5.0-beta.8xsai/embed: 0.5.0-beta.8 xsai/generate-speech: 0.5.0-beta.8 xsai/generate-text: 0.5.0-beta.8 xsai/generate-transcription: 0.5.0-beta.8 xsai/model: 0.5.0-beta.8 xsai/shared: 0.5.0-beta.8 xsai/shared-chat: 0.5.0-beta.8 xsai/stream-text: 0.5.0-beta.8 xsai/stream-transcription: 0.5.0-beta.8 xsai/tool: 0.5.0-beta.8 xsai/utils-chat: 0.5.0-beta.8各子包的package.json中依賴項一律寫作catalog:例如 packages/core-agent/package.jsonxsai-ext/providers: catalog:, xsai/generate-speech: catalog:, xsai/generate-text: catalog:, xsai/model: catalog:, xsai/shared: catalog:, xsai/shared-chat: catalog:, xsai/stream-text: catalog:, xsai/tool: catalog:這意味著即便選擇了多個細粒度包它們在工程內(nèi)也保證來自同一版本線不存在“xsai/stream-text與xsai/shared-chat類型不兼容”這類隱患。這是“多包細粒度選型”在工程上成立的前提值得在自己的項目中照搬。同一 catalog 中還登記了 xsAI 生態(tài)的擴展包pnpm-workspace.yamlxsai-apple-speech/*0.1.3Apple 平臺轉(zhuǎn)寫、xsai-ext/providers預定義 provider0.5.0-beta.8、xsai-transformers/*^0.1.0transformers.js 后端。參考文檔本身不涵蓋這些擴展包但它們印證了 xsAI 的邊界核心包保持 OpenAI 兼容的最小面平臺特定能力以xsai-*/擴展包形式外掛。導入建議三條規(guī)則與 AIRI 中的對應實踐參考文檔的 Import advice 部分給出三條建議逐條對應到倉庫事實“如果用戶明確在意體積從細粒度包導入?!盇IRI 全部 30 處xsai/*導入都來自細粒度包沒有一處import ... from xsai。例如語音模塊只取所需的一個函數(shù)// packages/stage-ui/src/stores/modules/speech.ts#L9 import { generateSpeech } from xsai/generate-speech這樣打包器只會把generateSpeech所在的模塊圖拉進 bundle傘包中其余 9 個功能的代碼不會進入產(chǎn)物?!叭绻脩粼趯懳臋n示例或希望只依賴一個包xsai是可接受的?!边@是對傘包的定位面向示例、教程與輕量項目xsai提供更簡潔的單一導入面。AIRI 主倉庫因為追求體積與邊界清晰沒有采用它但該豁免條件真實存在不要把它視為錯誤用法?!熬庉嫾扔写a庫時遵循倉庫已使用的包風格除非有充分理由改變。”這條在 AIRI 里體現(xiàn)為風格一致性工具定義統(tǒng)一從xsai/tool導入且按場景選擇tool()與rawTool()// packages/stage-ui/src/tools/debug.ts#L1 import { tool } from xsai/tool // packages/stage-ui/src/tools/web-search.ts#L3 import { rawTool } from xsai/tool // packages/core-agent/src/agents/spark-notify/tools.ts#L7 import { rawTool } from xsai/tool從 SKILL.md 的 API selection rules 可以推斷出兩者的分工tool()面向 Zod、Valibot 這類 Standard Schema 庫rawTool()面向已有原始 JSON Schema 的場景直接傳裸Tool對象僅在倉庫已使用該形狀時采用。AIRI 中既有tool()如 mcp.ts也有rawTool()并存正是“遵循既有形狀”規(guī)則的落地。源碼實證每個細粒度包在 AIRI 里被如何使用以下摘錄均出自倉庫源碼可直接點擊路徑繼續(xù)深入用于印證上表的選型邏輯xsai/stream-text流式對話主干。packages/core-agent/src/runtime/llm-service.ts 同時導入stepCountAtLeast來自xsai/shared-chat與streamText把 xsAI 的流事件text.delta、reasoning.delta、tool-call.done、tool-result.done等映射為 AIRI 內(nèi)部的StreamEvent契約。源碼注釋還提到stopWhen控制帶顯式停止謂詞的工具循環(huán)——這是流式包選型時容易被忽略的配套能力。xsai/generate-speechTTS 入口。packages/stage-ui/src/stores/modules/speech.ts 的 Pinia store 只依賴generateSpeech一個函數(shù)其余能力由 AIRI 自己的 provider 層補齊。xsai/stream-transcription流式轉(zhuǎn)寫類型。packages/stage-ui/src/libs/providers/stream-transcription/index.ts 基于StreamTranscriptionDelta、StreamTranscriptionResult類型擴展出 AIRI 的“可替換快照”事件transcript.text.snapshot并用自實現(xiàn)的 SSE 解析器歸一化音頻塊。這說明選包選的是類型契約 運行時原語上層協(xié)議仍由工程自行編排。xsai/embed嵌入能力。packages/stage-ui/src/components/scenes/Stage.vue 直接引用xsai/embed配合 catalog 中登記的xsai-transformers/embed提供本地嵌入后端。xsai/generate-text/xsai/model文本生成與模型列表查詢分別散見于各 provider 與設(shè)置模塊如 packages/stage-ui/src/stores/ai/chat-llm/llm.ts 的listModels引用面最廣對應“最常用功能配最小包”的選型結(jié)果。定位邊界OpenAI 兼容優(yōu)先而非通用 provider 抽象層參考文檔末尾的 Positioning reminder 只有一句但約束力很強xsAI 是有意為之的 OpenAI-compatible-firstOpenAI 兼容優(yōu)先不要把 xsAI 當作通用 provider 抽象層來推薦。這與 SKILL.md 中“不適用場景”完全一致當任務需要超出 OpenAI 兼容面的 provider 抽象、需要“全家桶”式 AI 應用框架、或依賴未通過 OpenAI 兼容接口暴露的 provider 專有 API 時不應選擇 xsAI。AIRI 的做法也印證了這一點它需要多 provider 管理時引入的是xsai-ext/providers這類顯式擴展包見 packages/core-agent/package.json而不是期待核心包提供萬能抽象。對讀者而言這條邊界直接影響選型決策如果你的目標 API 是 OpenAI 兼容端點含大量自托管網(wǎng)關(guān)按本文前述規(guī)則選最小包即可如果不是xsAI 包家族就不在候選集內(nèi)選型討論應另起。選型自檢清單綜合參考文檔與倉庫實踐在 AIRI 或同類工程中做包決策時可按以下順序自檢目標 API 是否 OpenAI 兼容否 → 停止xsAI 不適用。需要幾種能力只有一種 → 選對應最小功能包對照“逐包推薦”表。同時需要多種能力且希望單一導入面→ 可評估傘包xsai若體積敏感仍應保持細粒度包。是既有代碼庫嗎→ 沿用倉庫現(xiàn)有導入風格AIRI 全倉為細粒度包 pnpm catalog 統(tǒng)一版本不輕易切換。需要工具調(diào)用→xsai/tool下的tool()Standard Schema 庫或rawTool()原始 JSON Schema。多包并存時是否用 catalog/lockfile 統(tǒng)一版本AIRI 的答案見 pnpm-workspace.yaml。按此清單執(zhí)行既能繼承參考文檔的選型骨架也能保證與 AIRI 倉庫當前 0.5.0-beta.8 版本線下的真實依賴結(jié)構(gòu)一致?!久赓M下載鏈接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.項目地址: https://gitcode.com/GitHub_Trending/ai/airi創(chuàng)作聲明:本文部分內(nèi)容由AI輔助生成(AIGC),僅供參考