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