run-models

文档

• 参考文档：https://replicate.com/docs/llms.txt
• OpenAPI 架构：https://api.replicate.com/openapi.json
• MCP 服务：https://mcp.replicate.com
• 每个模型的文档：https://replicate.com/{owner}/{model}/llms.txt
• 请求文档页面以获取 Markdown 格式的响应时，请设置 Accept: text/markdown。

工作流

1. 选择合适的模型 - 使用 API 搜索，或询问用户。
2. 获取模型元数据 - 通过 API 获取输入和输出架构。
3. 创建预测 - 向 /v1/predictions 发送 POST 请求。
4. 轮询结果 - 持续 GET 预测，直到状态为 "succeeded"。
5. 返回输出 - 通常是生成内容的 URL。

获取输出的三种方式

1. 创建预测，从响应中保存其 id，并轮询直到完成。
2. 创建预测时设置 Prefer: wait 标头，以获取阻塞式同步响应。仅建议用于速度非常快的模型。最长等待 60 秒。
3. 创建预测时设置 HTTPS webhook URL，预测完成后 Replicate 会向该 URL 发送 POST 请求。

指南

• 使用 POST /v1/predictions 端点，因为它同时支持官方模型和社区模型。
• 每个模型都有自己的 OpenAPI 架构。务必获取并检查模型架构，确保设置的输入有效。即使是热门模型，其架构也会发生变化。
• 根据架构约束（minimum、maximum、enum 值）验证输入参数。不要生成违反约束的值。
• 不确定参数值时，请使用模型的默认示例，或省略可选参数。
• 除非有充分理由，否则不要设置可选输入。只使用必需输入，让模型使用默认值。
• 尽可能使用 HTTPS URL 作为文件输入。也可以发送 Base64 编码的文件，但应避免这样做。
• 并发发起多个预测。不要等一个预测完成后再开始下一个。
• 输出文件 URL 会在 1 小时后过期；如需保留，请使用 Cloudflare R2 等服务备份。
• Webhook 是接收和存储预测输出的好方法。

预测

• 预测会经历以下状态：starting -> processing -> succeeded / failed / canceled。
• 官方模型使用 owner/name 格式。社区模型需要 owner/name:version_id。
• POST /v1/predictions 端点同时处理这两种模型。

Webhook

• 创建预测时，将 webhook 设置为 HTTPS URL。预测完成后，Replicate 会向该 URL 发送完整的预测对象。
• 使用 webhook_events_filter 筛选事件：start、output、logs、completed。
• 使用 Webhook-ID、Webhook-Timestamp 和 Webhook-Signature 标头验证 webhook 签名。通过 GET /v1/webhooks/default/secret 获取签名密钥。

预测生命周期

• 设置 lifetime，自动取消运行时间过长的预测（例如 30s、5m、1h）。计时从创建时开始。

流式传输

• 支持流式传输的语言模型会在响应中包含 stream URL。使用 SSE 接收增量输出。

文件处理

• 文件输入优先使用 HTTPS URL。一个预测的输出 URL 可直接作为下一个模型的文件输入。
• 输出文件 URL 会在 1 小时后过期。如需保留，请立即下载并存储。

多模型工作流

• 通过将输出 URL 作为文件输入传递给下一个模型来串联模型。
• 并行启动所有相互独立的预测，然后收集结果。
• 输出 URL 有效期为 1 小时，足以完成流水线步骤。