Replicate 快速上手：从运行公开模型到部署自定义模型

Replicate 是一个通过云端 API 运行 AI 模型的平台。你不需要理解机器学习原理，也不需要自己维护 GPU 机器，就能调用别人已经发布的模型；也可以带上自己的训练数据做微调，或者把自定义模型部署上去。它适合两类人：一类是想在应用里快速接入图像生成、语音、放大等能力的开发者；另一类是自己写了模型代码、希望把它变成可调用 API 并自动扩缩容的模型作者。如果你只是想先跑通一次调用，可以从 Replicate 的公开模型开始；如果你要上线自己的模型，则需要走完创建模型、打包、部署这条链路。

准备工作

账号与组织

使用 Replicate 需要一个账号。个人使用直接在用户账号下创建模型即可；如果是团队协作，建议先在账号菜单里选择「Join or create organization」创建组织，或者访问 replicate.com/organizations/create。模型挂在组织下，团队成员可以共享访问权限和账单。

API Token

调用 API 需要 API Token。Token 属于账号级凭据，创建后应妥善保存，不要写进前端代码或提交到公开仓库。在代码里通常通过环境变量传入，例如 REPLICATE_API_TOKEN。

运行环境

按你选择的调用方式准备：

• Python：安装官方客户端库 replicate，需要 Python 3 环境。
• Node.js：安装 npm 包 replicate，需要 Node.js 运行时。
• HTTP：任何能发 HTTPS 请求的语言或工具都可以，不需要额外依赖。
• Google Colab：不想本地装环境时，可以直接在 Colab 笔记本里运行任意公开模型。

如果要部署自定义模型，还需要安装 Cog。Cog 是开源工具，负责把任意代码打包成标准的生产级容器，并自动生成 API 服务器。你只需要定义模型环境和预测逻辑，服务器、扩缩容和算力管理由 Replicate 负责。

费用与配额

Replicate 按实际用量计费，具体价格、免费额度与速率限制以官网当前信息为准。调用前建议先确认账号的计费状态，避免在批量任务中途因余额不足失败。

操作步骤

第一步：选择一个模型

Replicate 上的模型分为官方模型和社区模型，也有公开与私有之分。公开模型任何人都能发现和使用，私有模型只有所属用户或组织可见。每个模型都有若干版本（version），调用时需要指定具体版本，或者使用模型页面上给出的完整标识。

在模型页面上可以直接看到输入参数、输出示例和可复制的调用代码。第一次使用时，建议先在网页上试跑一次，确认输入输出符合预期，再写进代码。

第二步：用 Python 运行模型

安装客户端库：

pip install replicate

设置 Token 后调用模型。下面以图像生成类模型为例，把模型标识替换成你要用的那个：

import os
import replicate

os.environ["REPLICATE_API_TOKEN"] = "你的_token"

output = replicate.run(
    "owner/model-name:版本哈希",
    input={
        "prompt": "a photo of a hotdog on a plate",
    },
)

print(output)

replicate.run 会创建一次预测（prediction）并等待结果返回。输入是一个字典，键名必须与模型页面上列出的输入字段一致；字段名写错或类型不符，请求会被拒绝。

第三步：用 Node.js 运行模型

安装 npm 包：

npm install replicate

然后在脚本中调用：

import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.REPLICATE_API_TOKEN,
});

const output = await replicate.run(
  "owner/model-name:版本哈希",
  {
    input: {
      prompt: "a photo of a hotdog on a plate",
    },
  }
);

console.log(output);

Node.js 版本同样支持在浏览器之外的服务端环境运行。不要把 Token 暴露在客户端代码里。

第四步：直接调用 HTTP API

不依赖客户端库时，可以直接向 HTTP API 发请求。创建预测的基本形式是向模型的 predictions 端点 POST 一个 JSON 体，请求头带上 Authorization: Bearer <token> 和 Content-Type: application/json，请求体里放 version 和 input。返回结果中包含预测的 ID 和状态，可以据此轮询或配合 webhook 获取最终输出。

HTTP API 的完整字段定义可以参考 OpenAPI schema。平台还提供 llms.txt，方便把文档内容交给语言模型处理。

第五步：创建自定义模型

如果公开模型不能满足需求，就要创建自己的模型。在账号菜单里点击「Create model」，或者访问 replicate.com/create。创建时需要决定四件事：

• 名称：短且好记，例如 hotdog-detector。只能使用小写字母和连字符。
• 所有者：个人使用选自己的用户账号；团队协作选组织，以便共享访问和账单。
• 可见性：公开模型任何人都能发现和使用；私有模型只有所属用户或组织可见。
• 硬件：选择模型运行所需的 GPU 类型。平台提供 A100、H100、B200 等高端 GPU。

第六步：用 Cog 构建模型

模型用 Cog 打包。你需要定义两样东西：模型运行环境（依赖、系统包、Python 版本等）和预测逻辑（接收什么输入、返回什么输出）。Cog 会据此生成一个标准的容器镜像，其中包含一个符合 Replicate 规范的 API 服务器。

构建完成后，把模型推送到 Replicate，平台会为它创建一个版本。版本是模型的可调用快照，后续更新会生成新版本，旧版本仍然保留。

第七步：创建部署

模型版本可以直接按需调用，但如果要承载生产流量，应该创建部署（deployment）。部署是专用的推理实例，特点包括：

• 没有「吵闹邻居」，算力独享；
• 可以从零自动扩展到数千块 GPU，按需伸缩；
• 支持滚动部署，更新模型时不中断服务；
• 可以实时查看性能、成本和用量；
• 按实际使用量付费。

创建部署时指定模型版本和硬件配置，平台会负责拉起实例并对外提供 API 端点。

第八步：监控与迭代

部署上线后，在控制台查看请求量、延迟、错误率和费用。需要更新模型时，推送新版本并执行滚动部署，旧实例逐步被替换，期间服务保持可用。不再需要的部署可以删除，避免持续产生费用。

一个完整示例

下面把前面的步骤串起来，做一个最小可用的图像生成调用。假设你已经有一个公开的图像生成模型，模型标识为 owner/model-name，版本哈希为 abc123。

1. 准备环境

python -m venv venv
source venv/bin/activate
pip install replicate

2. 设置 Token

export REPLICATE_API_TOKEN=你的_token

3. 编写脚本

import replicate

output = replicate.run(
    "owner/model-name:abc123",
    input={
        "prompt": "an oil painting of a lighthouse at dusk",
        "num_outputs": 1,
    },
)

for item in output:
    print(item)

4. 运行

python generate.py

脚本会创建一次预测，等待模型执行完毕，然后打印输出。图像类模型的输出通常是文件 URL 列表，可以直接下载或在前端展示。如果输出是单个字符串而不是列表，说明该模型的输出结构不同，以模型页面上的说明为准。

5. 换成异步方式

当模型执行时间较长时，同步等待可能不合适。此时可以创建预测后立即拿到预测 ID，再通过查询预测状态获取结果，或者配置 webhook，让 Replicate 在预测完成时回调你的服务。webhook 需要你自己提供一个可公网访问的接收端点，并验证请求来源。

注意事项

输入字段必须匹配

每个模型的输入 schema 不同，字段名、类型、默认值都以模型页面为准。传了不存在的字段或类型不符，预测会直接失败。不要凭经验猜测参数名。

预测是有生命周期的

一次预测会经历创建、排队、运行、成功或失败等状态。长时间运行的预测可能因为超时或资源问题失败，代码里要处理失败状态，而不是假设一定会成功。

速率限制与安全审查

平台对 API 调用有速率限制，具体阈值以官网当前信息为准。部分输入会经过安全检查，被判定为不合规的请求可能被拒绝。批量任务应加入重试和退避逻辑。

数据保留

预测的输入和输出文件会按平台的数据保留策略存储，超过期限后可能被清理。需要长期保存的结果，应在生成后及时转存到自己的存储中。

密钥管理

模型运行所需的敏感信息（例如第三方 API Key）应通过 Secrets 配置，不要硬编码在模型代码里。Secrets 在运行时注入环境变量，不会出现在公开的模型文件中。

私有模型的可见性

私有模型只有所属用户或组织可见，但这不等于自动加密所有输出。分享预测结果时会生成公开链接，分享前确认其中不含敏感数据。

部署会产生持续费用

部署实例即使没有流量也可能产生费用，具体计费方式以官网当前信息为准。测试完成后及时删除不再使用的部署，避免账单意外增长。

自定义模型需要自己保证可运行

Cog 负责打包和生成 API 服务器，但模型本身的依赖、权重加载、显存占用需要你自己处理。本地能跑通不代表在目标 GPU 上能跑通，部署前应在对应硬件规格上验证。