企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手

本指南围绕仓库内 xsai 技能参考文档 展开，系统讲解 xsAI 在「嵌入向量、图像生成、语音合成、语音转录」四类媒体与嵌入场景下的包选择、核心参数与调用形态。作为 AIRI 项目 AI 能力层的底层运行时，xsAI 的相关包已实际用于语音合成与流式转录链路（见 core-agent 依赖 与 provider-inference 依赖）。读完本文，你将能直接调用@xsai/embed、@xsai/generate-image、@xsai/generate-speech、@xsai/generate-transcription与@xsai/stream-transcription完成从向量检索到实时语音交互的完整媒体处理。

xsAI 媒体 API 的定位：小而窄的 OpenAI 兼容运行时

在进入具体 API 之前，需要先理解 xsAI 的整体设计约束。根据 xsAI 技能主文档，xsAI 被定位为extra-small、Fetch-based、OpenAI-compatible-first的运行时，而不是一个覆盖所有供应商的通用 AI SDK。这一原则对媒体与嵌入 API 同样生效：

• small：优先选用能解决当前任务的最小粒度包，避免引入伞形xsai大包；
• Fetch-based：所有调用底层都基于标准fetch，因此天然可在 Node.js、浏览器、Workers 等任何具备 Fetch 能力的运行时复用；
• OpenAI-compatible-first：只承诺兼容 OpenAI 风格的请求/响应形状，不承诺覆盖非兼容供应商的私有 API。

媒体与嵌入类 API 遵循与文本生成相同的「共享心智模型」：apiKey、baseURL、model三项通常是实际调用中的必填项，外加可选的fetch、headers、abortSignal（详见 text-stream-tools 参考）。在 AIRI 的源码中可以看到这条原则的实际落地：例如 VOICEVOX 系列语音引擎定义 通过注入自定义fetch来拦截generateSpeech生成的 OpenAI 形状请求，再转发给本地引擎的 HTTP 接口，这正是「OpenAI 兼容在前、供应商差异由适配层收敛」的典型做法。

Embeddings：@xsai/embed的 embed 与 embedMany

包与核心导出

文本向量化使用@xsai/embed，它对外暴露两个导出：

• embed：对单条文本输入生成一个向量；
• embedMany：对批量文本输入生成一批向量，要求同一供应商、同一模型，适合一次调用处理多条记录。

典型输入参数：

最小可运行示例

recipes 参考 给出了使用本地 Ollama 端点的最小示例：

import { embed } from '@xsai/embed' const { embedding, usage } = await embed({ baseURL: 'http://localhost:11434/v1/', input: 'sunny day at the beach', model: 'all-minilm', })

返回结果包含embedding（向量数组）与usage（token 用量）。当需要对多条文本做索引或批量检索时，改用embedMany传入数组输入，减少往返次数。

在 AIRI 中的使用现状

从源码看，AIRI 的 Stage.vue 中保留了import { embed } from '@xsai/embed'的注释行，说明嵌入能力在 AIRI 中目前仍处于预留/评估阶段，尚未接入主链路。需要指出的是，仓库内没有独立的文本嵌入 provider 实现，若要在 AIRI 中启用向量检索，需要自行配置一个 OpenAI 兼容的嵌入端点（如本地 Ollama）或通过@xsai-ext/providers复用预设工厂（见 extensions 参考）。

图像生成：@xsai/generate-image

核心参数

图像生成使用@xsai/generate-image，面向 OpenAI 兼容的图像生成接口。常用选项：

返回值的归一化承诺

@xsai/generate-image的一个关键设计是：返回的图像被统一归一化为 data URL 并附带 MIME 类型。也就是说，无论上游返回的是 base64 字符串还是 URL，调用方拿到的都是自包含、可直接交给<img src>或 canvas 消费的 data URL 形态。这一点显著降低了上层应用做图像落盘、预览或二次传输的复杂度——不需要自己判断上游格式再分支处理。

语音合成：@xsai/generate-speech

核心参数与返回类型

文本转语音使用@xsai/generate-speech。常用选项：

返回值是二进制音频数据，可直接写入音频播放器、保存为文件或送入后续音频管线。

在 AIRI 中的实际接线方式

AIRI 的语音输出链路完整使用了@xsai/generate-speech：

• 依赖层面：core-agent/package.json 将@xsai/generate-speech声明为运行时依赖，配合 provider-inference 将 speech provider 作为devDependencies用于测试；
• 状态层面：speech 存储 直接import { generateSpeech } from '@xsai/generate-speech'，并按供应商（VOICEVOX、ElevenLabs、Azure Speech 等）维护音色目录VoiceInfo[]、pitch/rate 等语音设置；
• 适配层面：以 VOICEVOX 引擎定义 为例，generateSpeech会先构造一个 OpenAI 形状的请求体并拼出 URL，再调用注入的fetch。VOICEVOX 适配器通过readSpeechRequest从请求体中读取input（文本）与voice（style id）两个字段（define.ts 源码），忽略其余字段，然后调用引擎的audio_query/synthesis接口完成真正的合成，最后以audio/wav响应返回。

这一结构对二次开发有两点启示：其一，适配非 OpenAI 形状的本地引擎时，不需要改动generateSpeech的调用方，只需注入一个能读懂 OpenAI 请求体并转发到引擎的fetch；其二，VOICEVOX 配置 schema（define.ts 源码）中intonation、pitch、speed、volume的默认值分别为1 / 0 / 1 / 1，且引擎的speed参数会直接映射到generateSpeech的语速控制语义上。

引擎可达性校验

AIRI 为本地语音引擎配置了双层校验（define.ts 源码）：

• 配置校验：要求baseUrl是带http://或https://方案的绝对地址，默认端口 VOICEVOX 为http://localhost:50021/、AIVisSpeech 为http://localhost:10101/；
• 可达性校验：每 15 秒周期性探测引擎的/version接口（超时 5 秒），并在设置页提示「引擎未运行 / Base URL 端口不匹配」。

语音转录：unary 与 streaming 两种形态

两个包的取舍

转录场景拆分为两个包：

• @xsai/generate-transcription：unary（一次性）语音转文本，输入整段音频、返回完整文本，适合批量转录离线处理；
• @xsai/stream-transcription：流式语音转文本，持续接受音频块、增量产出文本，适合实时或逐句产出的场景（如语音对话、会议实时字幕）。

选择规则一句话概括：需要批处理用 unary，需要实时/增量输出用 streaming。两种形态的结果都遵循 xsAI 的流式结果形状，包含fullStream、textStream与text三件套。

流式转录的输入形态

从 stream-transcription 适配器 可以看到流式转录的可选输入：

该适配器把 SSE 转录端点转换成 xsAI 的结果形状：内部先用TransformStream将音频块归一化为Uint8Array，再通过TextDecoder逐行解析data:事件（parseSSELine 实现），把transcript.text.delta与transcript.text.snapshot分别写入textStream与fullStream。

浏览器流式上传的兼容性细节

适配器注释（index.ts 源码）记录了一个重要兼容性陷阱：Safari 27 对ReadableStream请求体会抛出NotSupportedError，Chromium 需要duplex: 'half'，而 Firefox/Safari 不暴露duplex。因此代码用'duplex' in Request.prototype探测能力：支持流式上传时直接以流为 body，否则先await new Response(audioStream).arrayBuffer()退化为一次性上传。在浏览器中做流式转录时，建议沿用这一能力探测而非硬编码 duplex。

AIRI 中的两个真实转录落地

AIRI 的转录能力由provider-inference承担，包含两类实现：

1. Sherpaw 本地 ASR（runtime.ts）：为每个转录请求在 Worker 中持有独立模型实例。输入要求是16000 Hz 单声道 PCM16 音频流，内部先经toFloat32FromPCM32转为 Float32，再调用streamTranscription。由于 Sherpaw 的文本流只追加增量、无法表达「更正」，AIRI 将事件流tee()成两份：一份喂给 xsAI 流式转录，另一份按句索引缓存 partial 快照，最终输出可替换的transcript.text.snapshot事件，实现「识别词更正」语义（runtime.ts 源码）。
2. Web Speech API 浏览器原生识别（provider.ts）：直接封装webkitSpeechRecognition/SpeechRecognition，以MediaStreamTrack为音频源，把原生onresult事件转换为 xsAI 的textStream/fullStream流。支持continuous、interimResults、maxAlternatives等原生选项，并在识别周期结束后以 100ms 延迟自动重启，保持长时间聆听。

包选择速查

结合 package-selection 参考 与媒体场景，推荐选择如下：

实战注意事项

• 不要硬编码密钥：托管供应商的apiKey在 Node.js 中从process.env读取，在浏览器中从localStorage读取；本地引擎（Ollama、VOICEVOX、Web Speech API）通常不需要 key；
• baseURL与model显式声明：这是 xsAI 的实际使用惯例，能避免隐式默认值带来的可移植性损失；
• 优先最小包：AIRI 各 package.json 均采用粒度依赖（如@xsai/generate-speech而非xsai），新增功能时保持这一风格；
• 适配层交给注入的fetch：非 OpenAI 兼容端点（本地 TTS 引擎、SSE 转录服务）通过自定义fetch或 SSE 解析适配器收敛，调用方代码保持 OpenAI 兼容形状不变。

综上，xsAI 的媒体与嵌入 API 遵循统一且克制的设计：四个领域、五个最小包、一套baseURL/model/apiKey心智模型，外加「流式返回三件套」的一致结果形状。AIRI 已在语音合成与流式转录上给出完整参考实现，可据此直接扩展图像生成与嵌入检索能力。

• 人工智能
• AI Agent
• MCP 服务
• 工具调用
• GUI 自动化
• 语音
• 数字人
• 交互助手