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

本篇指南基于 AIRI 仓库中的官方文档与配套源码，讲解如何在 AIRI 中配置 Replicate 作为云端图像生成（Artistry）服务商，覆盖 Token 获取、设置项逐项说明、内置模型预设，并深入 ReplicateProvider 的默认参数合并、占位符替换与任务轮询机制，读完后可独立完成配置、验证与故障排查。

一、Replicate 在 AIRI 中的定位

Replicate 让 AIRI 使用云端图像生成模型：无需自行部署 ComfyUI 或下载模型权重，直接向 Replicate 平台上公开的模型发起推理请求即可。完成配置后，可在设置 → 艺术模块中选择 Replicate 作为图像生成来源。

从源码结构看，AIRI 的 Artistry（艺术创作）模块支持三种提供商：comfyui（本地自托管）、replicate（云端）、nanobanana（Google AI Studio），三者统一注册在主进程的提供商注册表中：

// apps/stage-tamagotchi/src/main/services/airi/widgets/artistry-bridge.ts#L102-L105 export const artistryProviders = new Map<string, ArtistryProvider>() artistryProviders.set('comfyui', new ComfyUIProvider()) artistryProviders.set('replicate', new ReplicateProvider()) artistryProviders.set('nanobanana', new NanoBananaProvider())

所有提供商必须实现统一的ArtistryProvider接口（base.ts），核心方法包括：

• generate(request)：提交生成请求，返回任务句柄（jobId+providerJobId）；
• getStatus(jobId)：查询任务状态（queued / running / succeeded / failed / cancelled），成功时携带imageUrl；
• setJobCallback(jobId, callback)：可选的状态推送回调，Replicate 提供商实现了该能力，因此主进程无需纯轮询即可拿到结果；
• initialize(config)：用全局配置初始化提供商，Replicate 在此阶段创建客户端。

选择 Replicate 的典型动机：不想占用本地 GPU、不想维护模型部署，且希望从 Replicate 可用的模型列表中灵活挑选云端推理服务。

二、第一步：获取 API Token

1. 登录你的 Replicate 账户，进入账户设置页中的 API Tokens 页面，创建一个新的 API Token；
2. 确认账户已配置可用的计费方式或额度（云端推理按调用计费，无额度会导致请求被拒）；
3. 复制 Token 并妥善保存。界面文案中也提示了 Token 的形态：以r8_开头（见 settings.yaml 中 API 密钥字段说明）。

安全提醒：不要将 Token 提交到仓库、放入截图或发送给他人。泄露后，请立即在 Replicate 控制台撤销并创建新 Token。

三、第二步：在 AIRI 中配置

入口路径为设置 → 服务商 → 艺术 → Replicate（设置模块总览页在 settings/modules/artistry.vue 中以 RadioCard 形式列出none / comfyui / replicate / nanobanana四个选项，Replicate 对应路由/settings/providers/artistry/replicate）。

配置页组件为 replicate.vue，共四个设置项，与文档描述一一对应：

这四条持久化状态定义在 Pinia store artistry.ts 中，并通过useLocalStorageManualReset落地到本地存储：

// packages/stage-ui/src/stores/modules/artistry.ts#L58-L73 const replicateApiKey = useLocalStorageManualReset<string>('artistry-replicate-api-key', '', persistenceOptions) const replicateDefaultModel = useLocalStorageManualReset<string>( 'artistry-replicate-default-model', 'black-forest-labs/flux-schnell', persistenceOptions, ) const replicateAspectRatio = useLocalStorageManualReset<string>( 'artistry-replicate-aspect-ratio', '16:9', persistenceOptions, ) const replicateInferenceSteps = useLocalStorageManualReset<number>( 'artistry-replicate-inference-steps', 4, persistenceOptions, )

配置如何校验与同步

store 中有一个configured计算属性，用于判断当前活动提供商是否"已配置完整"——对 Replicate 而言，等价于 API 密钥非空（artistry.ts）：

if (activeProvider.value === 'replicate') { return !!replicateApiKey.value }

在桌面端，渲染进程还会通过 artistrySyncConfig 事件把replicateApiKey / replicateDefaultModel / replicateAspectRatio / replicateInferenceSteps等全局配置同步给主进程，写入 Electron 配置持久层。主进程侧的 schema 校验定义在 configs/artistry.ts，落盘到options.json，其默认值与前端 store 完全一致：

// apps/stage-tamagotchi/src/main/configs/artistry.ts#L5-L19 export const artistryConfigSchema = object({ artistryProvider: optional(string(), 'none'), artistryGlobals: optional(object({ ... replicateApiKey: optional(string(), ''), replicateDefaultModel: optional(string(), 'black-forest-labs/flux-schnell'), replicateAspectRatio: optional(string(), '16:9'), replicateInferenceSteps: optional(number(), 4), ... }), {}), })

四、内置模型预设：开箱即用的图像生成与编辑配方

仓库在 stage-shared/src/artistry.ts 中内置了REPLICATE_IMAGEGEN_PRESETS与REPLICATE_IMAGEEDIT_PRESETS两组预设，每个预设包含模型 ID、展示名、参考单价、提示词前缀模板和一组 provider 参数。图像生成预设覆盖不同风格的模型：

图像编辑预设则给出一个"Texture Swapper"示例：

// packages/stage-shared/src/artistry.ts#L138-L150 export const REPLICATE_IMAGEEDIT_PRESETS = [ { id: 'prunaai/p-image-edit', label: 'P-Image-Edit (Texture Swapper)', cost: 'Turbo', prompt: "The woman's dress is changed to black", preset: { turbo: true, images: [{ value: '{{IMAGE}}' }], aspect_ratio: '1:1', }, }, ]

注意{{IMAGE}}占位符——这正是 Replicate 提供商内建能力的一部分（见下文占位符替换机制）。这些预设中的cost是仓库内写死的参考标注，实际价格以 Replicate 模型页面为准。

五、ReplicateProvider 实现深读

5.1 初始化与请求参数合并

ReplicateProvider 用官方的replicateSDK（在 stage-tamagotchi/package.json 中声明为 workspace 依赖）构造客户端；initialize会把渲染进程传来的四个配置项注入为实例状态：

// apps/stage-tamagotchi/src/main/services/airi/widgets/providers/replicate.ts#L36-L51 async initialize(config: any): Promise<void> { if (config?.replicateApiKey) { this.apiKey = config.replicateApiKey this.replicate = new Replicate({ auth: this.apiKey }) } else { this.apiKey = '' this.replicate = null } if (config?.replicateDefaultModel) this.defaultModel = config.replicateDefaultModel if (config?.replicateAspectRatio) this.aspectRatio = config.replicateAspectRatio if (config?.replicateInferenceSteps) this.inferenceSteps = config.replicateInferenceSteps }

未配置 Token 时直接抛错Replicate provider is not configured. Missing API Key.，这也是"认证失败"排查的第一现场。

generate()的参数合并遵循三级优先级（replicate.ts）：

1. 默认基线：

const inputOptions: Record<string, any> = { go_fast: request.extra?.go_fast ?? true, aspect_ratio: request.extra?.aspect_ratio ?? this.aspectRatio, output_format: request.extra?.output_format ?? 'png', output_quality: request.extra?.output_quality ?? 80, num_inference_steps: request.extra?.num_inference_steps ?? this.inferenceSteps, }

可见代码内还隐含两个文档未提及的默认值：go_fast: true、output_format: 'png'、output_quality: 80。

2. 请求覆盖：来自角色卡/组件providerOptions的extra字段会整体合并覆盖默认值；其中image、internalJobId、remixId是内部字段会被剔除，prompt字段被刻意从覆盖中剥离（注释标注 "BY DESIGN"），以免覆盖上游已拼接了promptPrefix的提示词。
3. 模型解析：request.model || request.extra?.model || this.defaultModel，即"显式模型 > 附加字段模型 > 全局默认模型"。

5.2{{IMAGE}}/{{PROMPT}}占位符递归替换

预设中出现的{{IMAGE}}、{{PROMPT}}会在提交前被递归替换（replicate.ts）：

• {{IMAGE}}：替换为源图的 data URL。若传入的 base64 已带data:前缀则直接使用，否则包装为data:image/jpeg;base64,...——这让"以现有图片为输入"的编辑类模型（如 P-Image-Edit 预设）可以直接引用本地图像；
• {{PROMPT}}：替换为截断后的提示词。truncatePrompt默认上限380 字符，超出部分截断并追加...（replicate.ts），避免超长提示词触发模型端报错；
• 若extra中不含{{PROMPT}}占位符，则提示词会直接写入inputOptions.prompt并被同样截断。

替换函数对字符串、数组、嵌套对象均做深度遍历，因此images: [{ value: '{{IMAGE}}' }]这类结构也能被正确填充。

5.3 任务模型：异步执行与状态推送

Replicate 的run()是阻塞式等待完成的调用，但接口约定要求generate()立即返回任务句柄，因此实现上将生成放入后台任务（replicate.ts）：

// 返回句柄后立即返回，后台异步执行 const jobId = request.extra?.internalJobId || Math.random().toString(36).slice(2) this.runGeneration(jobId, model, inputOptions) return { jobId, providerJobId: jobId }

runGeneration内部调用this.replicate.run(model, { input })，并对返回值做三种形态的兼容提取（replicate.ts）：

1. SDK 新版本返回的FileUpload对象——取其url().href；
2. 带字符串url属性的对象——直接取url；
3. 纯字符串——URL 本身。

提取到的 URL 必须是http或data:前缀，否则按失败处理。状态机通过updateStatus写入jobResultsMap 并触发callbacks中注册的回调；完成后延迟 10 秒清理回调与结果，防止内存泄漏。

主进程侧的 artistry-bridge.ts 会优先检测setJobCallback：Replicate 提供商支持回调，因此走"回调等待"分支；对不支持回调的提供商则退化为每 2 秒轮询一次getStatus，整体超时 5 分钟（artistry-bridge.ts）。无头生成路径generateHeadless还额外做了请求去重：以提示词、模型、提供商、参数与全局配置的 SHA-256 指纹合并完全相同的在途请求，避免重复计费（artistry-bridge.ts）。

此外，widget 触发链路还有一个"触发指纹"防护：同一 widget 实例只有当mode:remixId:prompt组合发生变化时才会真正发起新的计费调用（artistry-bridge.ts），用于防止响应式 UI 循环造成的重复云端调用；失败时会清除指纹以允许重试。

六、第三步：验证配置

1. 打开设置 → 艺术，选择Replicate（对应globalProvider置为replicate，配置完整度由前述configured计算属性把关）；
2. 使用一条不含敏感信息的提示词生成图片；
3. 成功返回图片即表示 Token、模型 ID 和账户额度均可用。

由于artistry/comfy组件的 widget 在桥接层被强制设为无限 TTL（"Living Wall" 模式，见 artistry-bridge.ts），生成完成前组件会持续显示 running 状态与actionLabel（如 "Requesting cloud generation..."），可直接据此观察任务进展。

七、排查指南

结合文档与实现，把排查项落到具体代码位置：

失败状态下 widget 会保留错误信息（actionLabel: Error: ...截取前 50 字符），主进程日志前缀为providers-replicate，可据此过滤定位具体报错。

八、小结

AIRI 的 Replicate 集成是一个"配置最小化 + 参数可扩展"的设计：渲染进程只保存 API 密钥、默认模型、宽高比、推理步数四项持久化配置，其余细节通过预设（REPLICATE_IMAGEGEN_PRESETS/REPLICATE_IMAGEEDIT_PRESETS）与providerOptionsJSON 覆盖机制注入；主进程侧统一走ArtistryProvider接口，配合占位符替换、380 字符截断、回调式状态推送与触发指纹去重，在免部署的前提下提供可控的云端图像生成链路。若你需要更强的工作流定制，可参考同级的 ComfyUI 配置文档 对比两种方案的取舍。

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