Airi 中的 xsAI 扩展包选型指南xsai-ext/providers、responses 与 telemetry 的使用边界【免费下载链接】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 调用栈基于 xsAI——一个超小型的 OpenAI 兼容运行时其扩展能力由xsai-ext/*系列包提供。本文基于 Airi 仓库内置的 xsAI 技能参考文档 extensions.md完整梳理三大扩展包xsai-ext/providers、xsai-ext/responses、xsai-ext/telemetry的适用场景、定位边界与推荐规则并结合仓库中 9 个包的真实依赖与调用代码说明扩展包在 Airi 中的实际落地方式。读完后你可以明确什么需求该引入扩展包、什么需求用核心xsai/*包就够了、以及在 Airi 各模块中扩展包的典型用法。总则core-first扩展包只在必要时使用参考文档开篇给出了一条总则General rule默认优先使用核心xsai与xsai/*包只有当用户需要核心路径之外的扩展能力时才引入xsai-ext/*包。这一原则在 Airi 的 xsAI 技能入口 SKILL.md 中被进一步细化xsAI 被定位为超小型 OpenAI 兼容运行时而非通用 AI SDK其技能规则明确写着——只有当用户明确需要预定义 provider、OpenAI Responses API、或 OTEL 遥测这类扩展能力时才应阅读 extensions.md 这份参考。换言之这份文档本身被设计成按需查阅的补充资料而非默认路径的一部分。与 package-selection.md 对照可以看到完整的选型谱系核心细粒度包按能力拆分xsai/generate-text一元文本生成、xsai/stream-text流式文本/工具事件、xsai/generate-object与xsai/stream-object结构化输出、xsai/tool工具定义、xsai/embed嵌入、xsai/generate-image、xsai/generate-speech、xsai/generate-transcription、xsai/stream-transcription伞形包xsai仅在需要多个能力或希望单一导入面时使用扩展包xsai-ext/*核心之外、按场景叠加。核心包与扩展包之间的边界非常清晰核心路径覆盖 OpenAI 兼容面下的文本、流式、结构化工具、媒体与转写扩展路径解决的是预定义供应商工厂、Responses API 语义、可观测性这三个核心刻意不做的事。xsai-ext/providersOpenAI 兼容供应商的预定义工厂文档定位参考文档对该包的说明是当用户希望使用面向 OpenAI 兼容供应商的预定义 provider 工厂时使用。列出的用例包括避免重复编写baseURL与apiKey的接线代码创建可复用的 provider 预设preset通过一个薄薄的 helper 层对接 OpenAI 兼容供应商。定位Positioning部分有两点关键澄清这是一个便利层convenience layer不是通用的 provider 抽象如果用户把最小体积放在第一位直接使用baseURLapiKey的方式可能仍然更合适。Airi 仓库中的真实使用xsai-ext/providers是 Airi 依赖树中唯一被实际启用的扩展包。在 pnpm-workspace.yaml 的 catalog 中它被统一锁定为0.5.0-beta.8与核心包xsai/generate-text、xsai/stream-text、xsai/embed等保持同一版本线pnpm-lock.yaml 中还保留了历史解析记录0.4.4、0.5.0-beta.6并存在间接依赖xsai-ext/shared-providers0.4.0-beta.12从源码结构看它属于该扩展包家族的内部共享件。声明依赖的包共有 9 个覆盖了应用层、共享包层与集成层packages/core-agent/package.jsonpackages/stage-ui/package.jsonpackages/stage-pages/package.jsonpackages/stage-layouts/package.jsonapps/stage-web/package.jsonapps/stage-pocket/package.jsonapps/stage-tamagotchi/package.jsonintegrations/discord-bot/package.jsonplugins/airi-plugin-game-chess/package.json从仓库中确认到的两类实际用法类型导入core-agent 的 LLM 端口契约 以import type { ChatProvider } from xsai-ext/providers/utils作为流式接口的参数类型import type { ChatProvider } from xsai-ext/providers/utils import type { Message } from xsai/shared-chat export interface AgentLLMPort { stream: (model: string, chatProvider: ChatProvider, messages: Message[], options?: StreamOptions) Promisevoid }同样的ChatProvider类型还被 llm-service.ts、chat-orchestrator-runtime.ts 及其测试文件 chat-orchestrator-runtime.test.ts、spark-notify 的 agent 测试 引用stage-pocket 与 stage-web 的 performance-playground.vue 则同时导入ChatProvider与SpeechProviderWithExtraOptions。stage-pages 中大量语音/转写 provider 设置页如 alibaba-cloud-model-studio.vue也统一从xsai-ext/providers/utils导入SpeechProviderWithExtraOptions。运行时工厂discord-bot 的 TTS 管道 直接使用createOpenAI工厂创建 provider再与核心包xsai/generate-transcription组合完成语音转写——这是文档所说避免重复baseURLapiKey接线的典型实例。这一用法与文档用例完全吻合Airi 在需要跨模块共享 provider 契约ChatProvider/SpeechProviderWithExtraOptions类型以及创建 OpenAI 兼容预设的地方统一走xsai-ext/providers而单点、极小体积的场景仍直接使用核心包的baseURLapiKey直连方式。xsai-ext/responses面向 OpenAI Responses API 的扩展文档定位参考文档给出的用例OpenAI Responses API 的事件流event streams基于 Responses API 语义构建的函数调用function calling流程围绕 Responses API 输入/输出形状的归一化normalization。定位规则同样严格仅当用户明确需要 Responses API 行为时才使用当 Chat Completions 已经能解决问题时不要把它推荐为默认路径。仓库佐证在 pnpm-lock.yaml 中可以确认xsai-ext/responses0.5.0-beta.8已被解析进依赖树带zod4.4.3的 peer 记录但它并未出现在 9 个直接依赖xsai-ext/providers的业务包package.json中。从源码结构看Airi 当前主链路core-agent、stage-ui 的聊天流以 Chat Completions 语义运行Responses API 扩展处于依赖树已就绪、按需启用的状态——这恰好印证了文档仅在明确需要时才推荐的边界仓库为它保留了版本对齐但没有把任何默认路径建立在其上。xsai-ext/telemetryOTEL 遥测扩展参考文档对该包的说明用例为 xsAI 调用包裹 OpenTelemetry span构建遥测管道与可观测性集成定位它是扩展不是最小核心路径的一部分如果用户在最优化最小依赖足迹除非明确需要可观测性否则不应推荐它。关于仓库状态需要如实说明在 pnpm-lock.yaml 中未检索到xsai-ext/telemetry的解析记录当前依赖树中没有实际启用该包。值得注意的是Airi 的集成侧对可观测性有独立诉求例如 integrations/telegram-bot/deploy 下带有 otel-collector、prometheus、tempo、grafana 的部署配置但这些属于 bot 集成自身的观测栈并非 xsAI 调用层的 span 包裹。因此就 xsAI 而言telemetry 扩展在 Airi 中属于文档已登记、尚未落地的能力未来若要在 LLM 调用层接入 OTEL该扩展包是文档指定的入口。推荐规则把扩展包留在正确的位置参考文档结尾给出三条 Recommendation rules这也是 Airi 仓库依赖结构的实际写照核心推荐保持 core-first默认答案永远是核心xsai/xsai/*包参见 package-selection.md 中的最小可解决任务的包原则只在扩展包直接解决用户明确提出的需求时才提及它例如我要 OpenAI 兼容供应商工厂→providers我要 Responses API 事件流→responses我要 OTEL span→telemetry用户要最小安装时优先核心包并省略扩展包。对照 Airi 的实际情况核心能力文本/流式/结构化工具/语音/转写全部由 0.5.0-beta.8 的xsai/*细粒度包承载见 pnpm-workspace.yaml catalog 中xsai/embed、xsai/generate-speech、xsai/generate-text、xsai/stream-text、xsai/stream-transcription、xsai/tool、xsai/shared-chat等条目唯一的扩展包xsai-ext/providers仅承担类型契约 供应商工厂这一便利层职责。这正是扩展包锦上添花、不喧宾夺主的工程化体现。速查三个扩展包何时选扩展包解决的问题明确不要用的情形Airi 中的状态xsai-ext/providersOpenAI 兼容供应商预定义工厂、provider 预设、复用baseURL/apiKey接线极致最小体积场景此时直接baseURLapiKey直连更优已启用9 个包直接依赖承担ChatProvider等类型契约与createOpenAI工厂xsai-ext/responsesResponses API 事件流、其语义下的函数调用、输入/输出形状归一化Chat Completions 已能解决任务时的默认推荐依赖树中已有0.5.0-beta.8记录业务包未直接依赖按需启用xsai-ext/telemetryxsAI 调用的 OTEL span、遥测管道与可观测性集成以最小依赖足迹为优化目标且无需可观测性时依赖树中未见启用属于已登记未落地能力小结xsAI 生态的分层设计是核心xsai/*细粒度包守住 OpenAI 兼容的最小路径xsai-ext/*扩展包按场景叠加供应商便利层、Responses API、OTEL 遥测三类能力。Airi 仓库的依赖结构catalog 版本对齐、9 个包共享xsai-ext/providers的ChatProvider契约、discord-bot 中createOpenAI的工厂用法是这套选型规则的一份可运行的实证。遵循本文的边界——core-first、按需扩展、最小化安装时省略扩展——即可在 xsAI 体系中做出与 Airi 一致的、可维护的依赖决策。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考