AIRI 接入 Replicate 云图像生成：从 API Token 配置到源码级原理解析

AIRI 接入 Replicate 云图像生成：从 API Token 配置到源码级原理解析

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI 的 Artistry 模块支持多种图像生成后端，其中Replicate是开箱即用的云端推理方案：无需在本机部署任何图像模型，直接在 Replicate 平台的海量模型库中挑选模型完成文生图、图生图。本文以 replicate.md 为骨架，完整覆盖 Token 获取、AIRI 内配置、验证与排错全过程，并结合桌面端源码（provider 实现、配置 Schema、设置页 UI）深入讲解底层调用链，读完即可独立完成配置并理解其工作原理。

为什么选择 Replicate？

AIRI 内置的图像生成提供方（Provider）有三类：本地 ComfyUI、云端 Replicate、以及 Google AI Studio 的 Nano Banana。Replicate 的定位非常明确——云端模型推理服务（见 settings.yaml 中的描述 "Cloud-based model inference service"）：

• 不需要 GPU、不需要本机部署 Stable Diffusion / FLUX 等模型；
• 可以在 Replicate 平台上自由切换不同厂商、不同版本的模型；
• 按调用计费，适合不想维护推理环境、或希望快速试错多种模型的用户。

如果你更倾向把图像模型部署在自己机器上（例如通过 WSL 运行 ComfyUI），可以改用 AIRI 的本地方案；而选择云服务时，Replicate 的配置门槛最低，只需一个 API Token 和模型 ID。

第一步：获取 Replicate API Token

1. 登录 Replicate 账户的 API Tokens 页面，点击创建一个新的 API token。
2. 确认账户已绑定可用的计费方式或拥有足够的余额/积分，因为每次图像生成都会消耗配额。
3. 复制生成的 token 并妥善保存。Replicate 的 API token 以r8_开头（AIRI 设置页的占位提示即为r8_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX，见 settings.yaml）。

API Token 安全须知：不要把 token 提交到代码仓库、截图或分享给他人。一旦怀疑 token 泄露，应立即在 Replicate 控制台吊销并重新生成。

第二步：在 AIRI 中配置 Replicate

配置入口为Settings → Providers → Artistry → Replicate，对应设置页源码 replicate.vue。设置页共四个字段：

具体操作：

1. 打开Settings → Providers → Artistry → Replicate。
2. 将 API Token 粘贴到 API Key 输入框。
3. 输入模型 ID。AIRI 默认使用black-forest-labs/flux-schnell；若要更换模型，请使用 Replicate 模型页上显示的完整准确 ID（如black-forest-labs/flux-schnell这种owner/model格式），写错会导致请求被拒。
4. 按需调整默认宽高比与推理步数。

需要说明的是，配置页面里Replicate.ai (Cloud)提供方是否可见还受isCustomProvidersDisabled()控制（见 artistry.vue）：当该开关关闭自定义 Provider 时，Replicate 与 Nano Banana 选项会被隐藏，仅保留 None 与本地 ComfyUI。

配置的存储与默认值

Replicate 相关配置并非写死在代码里，而是由三层结构共同承载：

1. 渲染进程 Pinia Store（artistry.ts）：通过useLocalStorageManualReset持久化到 localStorage，键名分别为artistry-replicate-api-key、artistry-replicate-default-model、artistry-replicate-aspect-ratio、artistry-replicate-inference-steps，默认值与设置页一致（模型black-forest-labs/flux-schnell、比例16:9、步数 4）。
2. 主进程配置 Schema（artistry.ts）：valibot 定义的artistryConfigSchema同样声明了replicateApiKey、replicateDefaultModel、replicateAspectRatio、replicateInferenceSteps四个字段及其默认值，配置持久化到artistry/options.json。
3. 运行时全局配置同步：渲染进程通过artistrySyncConfig桥接调用把 globals 同步到主进程（见 artistry-bridge.ts），主进程将其写入配置并缓存到角色卡级默认值。

这套"Store + 主进程 Schema + 桥接同步"的结构意味着：全局设置可以作为兜底，而每个角色卡（Character Card）还能在自身 artistry 配置中覆盖 provider、model 与参数（对应ArtistryModuleSettings中的providerOptions，见 base.ts）。

源码视角：一次 Replicate 生成请求的完整链路

配置完成后，AIRI 桌面端实际调用的是ReplicateProvider（replicate.ts）。它实现了统一的ArtistryProvider接口（base.ts），由 Artistry Bridge 负责调度。整条链路可以概括为：

1. 注册与初始化：Bridge 维护artistryProviders注册表（comfyui/replicate/nanobanana三个实例，见 artistry-bridge.ts）。触发生成前，initialize(config)读取replicateApiKey并实例化官方ReplicateSDK（new Replicate({ auth: apiKey })）；未配置 Key 时replicate为null，generate()会直接抛出Replicate provider is not configured. Missing API Key.。

2. 构造请求参数：generate()以一组默认输入为起点（见 replicate.ts）：

   const inputOptions = { go_fast: true, // 快速模式开关 aspect_ratio: this.aspectRatio,// 默认 16:9 output_format: 'png', // 输出格式 output_quality: 80, // 输出质量 num_inference_steps: this.inferenceSteps, // 默认 4 }

3. 覆盖与占位符：如果角色卡的 "JSON Parameters" 中提供了额外参数，会合并覆盖默认值；其中prompt被刻意剥离，避免覆盖 Bridge 已拼接了promptPrefix前缀的提示词。此外还支持{{PROMPT}}与{{IMAGE}}两种占位符的递归替换（可用于图生图/remix），超长提示词会被截断到 380 字符。

4. 异步执行与轮询：generate()立即返回{ jobId, providerJobId }，真正的replicate.run(model, { input })在后台执行；由于 Replicate 不提供回调式状态推送，Bridge 采用每 2 秒轮询一次getStatus()、最长 5 分钟超时的等待策略（见 artistry-bridge.ts）。

5. 输出解析：run()的返回可能是单个字符串 URL、字符串数组或FileUpload对象，Provider 会依次尝试FileUpload.url()、对象url属性、纯字符串三种形态提取图片地址，成功后以succeeded+imageUrl回调，失败则记录failed+ 错误信息；任务完成 10 秒后清理回调与结果缓存，防止内存泄漏。

6. 结果回传：无论是对话内联、背景还是浮层 Widget，最终图片都会以 URL 形式交给渲染进程；无头（headless）场景下 Bridge 还会把图片下载并转换为 base64 data URL（见 artistry-bridge.ts）。

值得注意的是，Bridge 对同一 Widget 的相同触发指纹（mode + remixId + prompt）做了去重，避免响应式 UI 循环引发重复的计费调用；无头请求也按 prompt/options/globals 的哈希指纹去重。这从工程层面保护了用户的云额度。

验证配置是否生效

配置完成后按以下顺序验证（对应文档的 Verify 章节）：

1. 打开Settings → Modules → Artistry，在 Provider 卡片中选择Replicate.ai (Cloud)（对应 artistry.vue 中的replicate选项；若该卡片不可见，请检查自定义 Provider 是否被禁用）。
2. 打开Settings → Modules → Consciousness，选择一个**支持工具/函数调用（tool/function calling）**的对话模型——因为"让角色生成图片"本质上是一次工具调用，对话模型必须能把用户意图转成 Artistry 生成请求。
3. 返回聊天窗口，让 AIRI 生成一张非敏感的图片。
4. 若返回了图片，说明 token、模型 ID、账户配额与工具调用链路全部正常。

常见问题排查

• 认证失败（Authentication failed）：确认粘贴的是完整的 API token（r8_开头、包含全部字符），注意不要混入首尾空格。
• 请求被拒绝（Request denied）：依次检查账户余额/积分是否充足、该模型对你的账户是否开放访问、以及模型 ID 是否与 Replicate 模型页完全一致。
• 生成结果不符合预期：确认所选模型支持的宽高比与参数范围（不同模型对aspect_ratio、num_inference_steps等参数的取值约束不同），然后调整推理步数——步数过低容易出现细节粗糙，过高则耗时和费用上升——或直接更换其他模型。
• Provider 报错Missing API Key：说明 Key 未同步到主进程，回到 Settings → Providers → Artistry → Replicate 重新保存一次配置，并确认 Artistry 模块中已选中 Replicate 提供方。

小结

Replicate 为 AIRI 提供了零部署成本的云端图像生成能力：配置上只需要 API Token + 模型 ID + 宽高比/步数四个要素；架构上由ReplicateProvider封装官方 SDK、由 Artistry Bridge 统一调度轮询与状态回传，并配有参数覆盖、占位符替换、请求去重等工程细节。掌握本文的配置与排查方法后，你可以进一步在角色卡的 artistry 配置（providerOptions）中按角色定制模型与参数，实现"不同角色、不同画风"的差异化图像表现。

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi