⏱️ 异步推理

异步推理是平台提供的一项异步请求机制，允许客户端以**“提交即忘”（fire-and-forget）**的方式发起推理请求，立即获得一个任务ID（job_id），后续通过轮询该ID获取最终结果。该功能仅限 Gateway 使用，Go SDK 不支持，且必须配置 Logs Store 才能启用。

✨ 核心特性

非阻塞交互：客户端提交请求后立即获得响应，无需等待推理完成，避免长连接超时
任务持久化：任务状态和结果持久化存储，支持随时查询，无惧网络中断
仅支持文生图、文生视频推理场景
幂等查询：结果可重复查询，重复轮询不会产生额外成本
削峰填谷：天然具备流量缓冲能力，突发流量下自动排队，避免网关雪崩
完整生态兼容：后台执行触发全量插件链路，治理、日志、成本统计与同步请求完全一致

🔄 工作流程

mermaid

flowchart LR
    A[客户端提交异步请求] --> B[返回202 Accepted + job_id]
    B --> C[任务进入后台队列]
    C --> D[工作线程拾取任务执行推理]
    D --> E[结果持久化存储]
    F[客户端轮询job_id] --> E
    E --> F[返回最终结果]

请求提交：客户端发送请求到异步端点，网关立即返回任务ID
排队执行：任务进入后台队列，由工作线程异步执行
结果存储：推理完成后，结果和状态持久化存储
结果查询：客户端通过job_id轮询获取执行结果（成功/失败）

📋 支持的端点列表

请求类型	提交端点 (POST)	轮询端点 (GET)
图像生成（文生图）	`/v1/async/images/generations`	`/v1/async/images/generations/{job_id}`
视频生成（文生视频）	`/v1/async/videos/generations`	`/v1/async/videos/generations/{job_id}`

⚠️ 异步端点不支持流式传输（Streaming）。

Submitting a Request

Use the same JSON body as the synchronous endpoint, but switch to the /v1/async/ path.

bash

curl -X POST http://localhost:8080/v1/async/images/generations \
  -H "Content-Type: application/json" \
  -H "x-bf-vk: sk-bf-your-virtual-key" \
  -H "x-bf-async-job-result-ttl: 3600" \
  -d '{
    "model": "stabilityai/stable-diffusion-xl-base-1.0",
    "prompt": "A beautiful sunset over the ocean, 4k, high resolution",
    "n": 1,
    "size": "1024x1024"
  }'

Response (202 Accepted)

json

{
  "id": "1e89b165-d4fe-49e8-beb2-3e157f2df02f",
  "status": "pending",
  "created_at": "2026-02-19T08:10:17.831Z"
}

Polling for Results

Use GET on the matching endpoint with the returned job_id.

bash

curl -X GET http://localhost:8080/v1/async/images/generations/1e89b165-d4fe-49e8-beb2-3e157f2df02f \
  -H "x-bf-vk: sk-bf-your-virtual-key"

Response codes:

202 Accepted: job is still pending or processing
200 OK: job is completed or failed

Pending example (202)

json

{
  "id": "1e89b165-d4fe-49e8-beb2-3e157f2df02f",
  "status": "pending",
  "created_at": "2026-02-19T08:10:17.831Z"
}

Completed example (200)

json

{
  "id": "1e89b165-d4fe-49e8-beb2-3e157f2df02f",
  "status": "completed",
  "created_at": "2026-02-19T08:10:17.831Z",
  "completed_at": "2026-02-19T08:10:19.412Z",
  "expires_at": "2026-02-19T09:10:19.412Z",
  "status_code": 200,
  "result": {
    "id": "img-123",
    "object": "images.generation",
    "created": 1740288617,
    "data": [
      {
        "url": "https://example.com/generated-sunset.png",
        "revised_prompt": "A beautiful sunset over the ocean, 4k, high resolution"
      }
    ]
  }
}

Failed example (200)

json

{
  "id": "1e89b165-d4fe-49e8-beb2-3e157f2df02f",
  "status": "failed",
  "created_at": "2026-02-19T08:10:17.831Z",
  "completed_at": "2026-02-19T08:10:19.412Z",
  "expires_at": "2026-02-19T09:10:19.412Z",
  "status_code": 429,
  "error": {
    "error": {
      "message": "rate limit exceeded",
      "type": "rate_limit_error"
    }
  }
}

📊 任务生命周期状态

状态	含义	触发条件
`pending`	任务已创建并进入队列	提交后立即返回
`processing`	后台工作线程已拾取任务	工作线程开始执行
`completed`	操作成功，结果已存储	服务商调用成功完成
`failed`	操作失败，错误已存储	服务商调用返回错误

⏳ 结果TTL与过期清理

默认TTL：3600秒（1小时），从任务完成时间起算，而非提交时间
全局配置：通过配置 client.async_job_result_ttl 设置服务端默认值
请求级覆盖：使用请求头 x-bf-async-job-result-ttl 指定秒数，若值无效或 ≤0 则回退至默认TTL
过期行为：轮询过期任务将返回 404 Job not found or expired
清理机制：过期任务每分钟自动清理一次

🔐 虚拟密钥授权

任务绑定：若提交时使用了虚拟密钥（x-bf-vk），该密钥身份会与任务绑定
轮询验证：轮询时必须提供相同的虚拟密钥值，否则返回404
公开任务：未使用虚拟密钥创建的任务不限定调用者，任何通过网关认证的请求均可轮询

📈 可观测性

日志标记：异步执行会像同步请求一样记录日志，日志元数据中标记 isAsyncRequest: true，在Logs UI中显示Async徽章
全链路插件：后台执行仍会触发完整的插件链路（治理、日志、成本追踪等），确保审计和计费一致性

🎯 核心价值

同步请求的痛点	Async Inference 的解决方案
🕒 长时任务阻塞连接：复杂推理（如图像生成）可能需要几十秒甚至分钟级响应，HTTP连接易超时，且占用网关线程	客户端提交后立即获得job_id，连接即可关闭，无需保持长连接
🔄 客户端重试困难：同步请求失败（网络闪断、超时）时，客户端难以判断服务端是否已处理，重试可能导致重复消费或数据不一致	任务状态持久化，客户端可随时幂等地轮询结果，失败时可精确获取错误信息
📈 后端压力不可控：突发流量下同步请求堆积会耗尽网关资源，导致雪崩	请求先入队列，由后台工作线程按能力消费，天然具备削峰填谷能力
❓ 进度不可见：同步请求只有成功/失败两种终态，缺乏中间状态	提供 pending → processing → completed/failed 的生命周期可见性
💸 资源浪费：同步请求在等待 AI 服务商响应时，网关线程处于阻塞状态，大量并发会消耗内存和文件描述符	网关仅需处理轻量级的队列写入和状态查询，推理执行完全交由后台工作池

📌 典型应用场景

1. 长时间运行的推理任务

高分辨率图像生成：Stable Diffusion等模型生成4K图像需数十秒
长视频生成：生成几分钟甚至更长的AI视频需数十秒到数分钟

2. 需要可靠性的关键业务

批量图像/视频生成：一次性提交大量生成任务，无需等待，完成后统一获取结果
内容审核类工作流：AI审核图像/视频内容后，结果需可靠存储供人工复检，异步模式确保结果不丢失

3. 资源受限的客户端

移动端/IoT设备：网络不稳定，无法维持长时间HTTP连接，异步轮询更健壮
Serverless函数：云函数执行时长通常有限制（如AWS Lambda最长15分钟），异步任务可轻松突破此限制

4. 微服务架构中的服务解耦

下游服务无需等待AI服务响应，可将任务ID写入消息队列，由其他服务异步消费结果，实现事件驱动架构

💡 与平台现有能力联动

虚拟密钥隔离：不同租户的异步任务通过虚拟密钥隔离，互不干扰
故障转移：若后台推理过程中主服务商失败，Fallbacks机制仍会触发，异步任务同样具备高可用性
成本追踪：异步任务完成后的用量数据会正常计入成本统计和治理日志，财务一致性不受影响

⚠️ 使用前提

Async Inference 不是默认开启的，需要满足：

部署模式为 Gateway（非嵌入式SDK）
Logs Store 已配置（用于持久化任务状态）
客户端需实现轮询逻辑（平台目前仅支持轮询模式，Webhook回调功能开发中）

简而言之，Async Inference 让平台从单纯的 API 代理升级为具备任务队列能力的 AI 网关，尤其适合生产环境中的长时间、高价值推理场景。

⏱️ 异步推理 ​

✨ 核心特性 ​

🔄 工作流程 ​

📋 支持的端点列表 ​

Submitting a Request ​

Polling for Results ​

📊 任务生命周期状态 ​

⏳ 结果TTL与过期清理 ​

🔐 虚拟密钥授权 ​

📈 可观测性 ​

🎯 核心价值 ​

📌 典型应用场景 ​

1. 长时间运行的推理任务 ​

2. 需要可靠性的关键业务 ​

3. 资源受限的客户端 ​

4. 微服务架构中的服务解耦 ​

💡 与平台现有能力联动 ​

⚠️ 使用前提 ​

⏱️ 异步推理

✨ 核心特性

🔄 工作流程

📋 支持的端点列表

Submitting a Request

Polling for Results

📊 任务生命周期状态

⏳ 结果TTL与过期清理

🔐 虚拟密钥授权

📈 可观测性

🎯 核心价值

📌 典型应用场景

1. 长时间运行的推理任务

2. 需要可靠性的关键业务

3. 资源受限的客户端

4. 微服务架构中的服务解耦

💡 与平台现有能力联动

⚠️ 使用前提