chenchen/pingtai_agent

Fork 1

Files

T

zhanggangyong 09d45476ef 备份

2026-03-15 15:34:11 +00:00

11 KiB

Raw Blame History

GCP 批量推理 Agent 使用指南

概述

GCP Batch Agent 是一个基于 Vertex AI 的批量推理服务，支持 Flex PayGo 模式。您只需传入 Cloud Storage 地址，Agent 会自动提交批量作业、监控状态并返回结果。

默认模型: gemini-2.5-flash

快速开始

第一步：授权存储桶访问

在使用本服务前，您需要给 Agent 服务账号授权访问您的 Cloud Storage 存储桶。

Agent 服务账号邮箱：

taijiclound@gemini-20251105-b.iam.gserviceaccount.com

方式一：使用 gsutil 命令

# 授权读取权限（用于读取输入文件）
gsutil iam ch serviceAccount:taijiclound@gemini-20251105-b.iam.gserviceaccount.com:objectViewer gs://您的存储桶名称

# 授权写入权限（用于写入输出结果）
gsutil iam ch serviceAccount:taijiclound@gemini-20251105-b.iam.gserviceaccount.com:objectCreator gs://您的存储桶名称

方式二：在 GCP 控制台操作

进入 Cloud Storage 控制台
选择您的存储桶 → 点击"权限"标签
点击"授予访问权限"
添加主账号：taijiclound@gemini-20251105-b.iam.gserviceaccount.com
选择角色：
- Storage Object Viewer（读取）
- Storage Object Creator（写入）

第二步：准备输入文件

输入文件必须是 JSONL 格式（每行一个 JSON 请求）或 JSON 格式。

文本请求示例 (input.jsonl)：

{"request":{"contents":[{"role":"user","parts":[{"text":"什么是人工智能？"}]}]}}
{"request":{"contents":[{"role":"user","parts":[{"text":"用简单的话解释机器学习。"}]}]}}
{"request":{"contents":[{"role":"user","parts":[{"text":"深度学习有哪些应用？"}]}]}}

带系统提示的请求：

{"request":{"contents":[{"role":"user","parts":[{"text":"翻译成英文：你好世界"}]}],"systemInstruction":{"parts":[{"text":"你是一个专业的翻译。"}]}}}

多模态请求（图片）：

{"request":{"contents":[{"role":"user","parts":[{"text":"描述这张图片"},{"fileData":{"mimeType":"image/jpeg","fileUri":"gs://您的存储桶/images/photo1.jpg"}}]}]}}

多模态请求（视频）：

{"request":{"contents":[{"role":"user","parts":[{"text":"总结这个视频"},{"fileData":{"mimeType":"video/mp4","fileUri":"gs://您的存储桶/videos/video1.mp4"}}]}]}}

第三步：上传输入文件

gsutil cp input.jsonl gs://您的存储桶/batch-input/input.jsonl

第四步：提交批量作业

curl -X POST http://服务地址/api/v1/batch/submit \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "input_uri": "gs://您的存储桶/batch-input/input.jsonl",
    "output_uri": "gs://您的存储桶/batch-output/"
  }'

API 接口说明

1. 提交批量作业

请求：

POST /api/v1/batch/submit

请求参数：

参数	类型	必填	说明
input_uri	string	是	输入文件的 GCS 路径，如 `gs://bucket/input.jsonl`
output_uri	string	是	输出目录的 GCS 路径，如 `gs://bucket/output/`
model	string	否	模型名称，默认 `gemini-2.5-flash`
display_name	string	否	作业显示名称

请求示例：

curl -X POST http://服务地址/api/v1/batch/submit \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "input_uri": "gs://my-bucket/input.jsonl",
    "output_uri": "gs://my-bucket/output/",
    "model": "gemini-2.5-flash",
    "display_name": "my-batch-job"
  }'

响应示例：

{
  "success": true,
  "message": "批量作业已提交",
  "job": {
    "job_id": "projects/xxx/locations/us-central1/batchPredictionJobs/123456789",
    "job_name": "my-batch-job",
    "state": "JOB_STATE_PENDING",
    "input_uri": "gs://my-bucket/input.jsonl",
    "output_uri": "gs://my-bucket/output/",
    "model": "publishers/google/models/gemini-2.5-flash",
    "create_time": "2026-03-05T07:30:00.000000Z"
  }
}

2. 查询作业状态

请求：

GET /api/v1/batch/status/{job_id}

请求示例：

# 使用简短 ID
curl "http://服务地址/api/v1/batch/status/123456789" \
  -H "api-key: 您的API密钥"

# 使用完整 job_id
curl "http://服务地址/api/v1/batch/status/projects/xxx/locations/us-central1/batchPredictionJobs/123456789" \
  -H "api-key: 您的API密钥"

响应示例：

{
  "success": true,
  "job": {
    "job_id": "projects/xxx/locations/us-central1/batchPredictionJobs/123456789",
    "job_name": "my-batch-job",
    "state": "JOB_STATE_RUNNING",
    "input_uri": "gs://my-bucket/input.jsonl",
    "output_uri": "gs://my-bucket/output/",
    "model": "publishers/google/models/gemini-2.5-flash",
    "create_time": "2026-03-05T07:30:00.000000Z",
    "start_time": "2026-03-05T07:31:00.000000Z",
    "progress": {
      "total_count": 1000,
      "succeeded_count": 450,
      "failed_count": 2
    }
  }
}

3. 列出作业

请求：

GET /api/v1/batch/list

请求参数：

参数	类型	必填	说明
page_size	int	否	每页数量，默认 10
filter_str	string	否	过滤条件

请求示例：

curl "http://服务地址/api/v1/batch/list?page_size=10" \
  -H "api-key: 您的API密钥"

响应示例：

{
  "success": true,
  "total": 2,
  "jobs": [
    {
      "job_id": "projects/xxx/locations/us-central1/batchPredictionJobs/123456789",
      "job_name": "my-batch-job-001",
      "state": "JOB_STATE_SUCCEEDED",
      "create_time": "2026-03-05T07:30:00.000000Z"
    },
    {
      "job_id": "projects/xxx/locations/us-central1/batchPredictionJobs/123456788",
      "job_name": "my-batch-job-002",
      "state": "JOB_STATE_RUNNING",
      "create_time": "2026-03-05T08:00:00.000000Z"
    }
  ],
  "next_page_token": null
}

4. 取消作业

请求：

POST /api/v1/batch/cancel/{job_id}

请求示例：

curl -X POST "http://服务地址/api/v1/batch/cancel/123456789" \
  -H "api-key: 您的API密钥"

响应示例：

{
  "success": true,
  "message": "作业取消请求已发送",
  "job": {
    "job_id": "projects/xxx/locations/us-central1/batchPredictionJobs/123456789",
    "job_name": "my-batch-job",
    "state": "JOB_STATE_CANCELLING"
  }
}

作业状态说明

状态	说明
JOB_STATE_QUEUED	作业已排队，等待资源
JOB_STATE_PENDING	作业待处理
JOB_STATE_RUNNING	作业正在运行
JOB_STATE_SUCCEEDED	作业成功完成
JOB_STATE_FAILED	作业失败
JOB_STATE_CANCELLING	作业正在取消
JOB_STATE_CANCELLED	作业已取消
JOB_STATE_PARTIALLY_SUCCEEDED	作业部分成功

获取输出结果

作业完成后，结果会自动保存到您指定的输出目录。

输出文件格式：

{"status":"","response":{"candidates":[{"content":{"role":"model","parts":[{"text":"人工智能是..."}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":150}}}
{"status":"","response":{"candidates":[{"content":{"role":"model","parts":[{"text":"机器学习是人工智能的一个子集..."}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":200}}}

下载输出结果：

gsutil cp -r gs://您的存储桶/batch-output/ ./local-output/

支持的模型

模型	说明
gemini-2.5-flash	默认模型，快速响应
gemini-2.5-pro	高性能模型
gemini-2.0-flash	上一代快速模型
gemini-1.5-flash	稳定版快速模型
gemini-1.5-pro	稳定版高性能模型

常见问题

1. 403 Permission Denied

原因：Agent 服务账号无权访问您的存储桶。

解决方案：按照"第一步：授权存储桶访问"的说明，给服务账号授权。

2. 404 Not Found

原因：输入文件不存在。

解决方案：检查 GCS 路径是否正确，确保文件已上传。

3. 400 Invalid Request

原因：输入文件格式错误。

解决方案：确保输入文件是有效的 JSONL 格式，每行一个完整的 JSON 对象。

4. 作业长时间处于 PENDING 状态

原因：Flex PayGo 模式下，作业可能需要排队等待资源。

解决方案：耐心等待，大型作业可能需要较长时间。

计费说明

Flex PayGo 模式：按实际处理的请求数计费
中途取消：只收取已完成部分的费用
失败请求：不收费

详细定价请参考 Vertex AI 定价页面。

最佳实践

批量大小：建议每个 JSONL 文件包含 100-10000 个请求
文件组织：使用有意义的目录结构，如 gs://bucket/batch-jobs/2026-03-05/input.jsonl
监控频率：对于大型作业，建议每 1-5 分钟查询一次状态
错误处理：检查输出文件中的 status 字段，处理失败的请求

MCP 接口

本服务同时支持 MCP (Model Context Protocol) 接口，可用于 AI Agent 集成。

MCP 端点

端点	方法	说明
/mcp	POST	MCP JSON-RPC 端点
/mcp/sse	GET	MCP SSE 连接端点
/mcp/sse	POST	MCP SSE 请求端点

获取工具列表

curl -X POST http://服务地址/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

调用工具

提交批量作业：

curl -X POST http://服务地址/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "submit_batch_job",
      "arguments": {
        "input_uri": "gs://您的存储桶/input.jsonl",
        "output_uri": "gs://您的存储桶/output/"
      }
    }
  }'

查询作业状态：

curl -X POST http://服务地址/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_job_status",
      "arguments": {
        "job_id": "123456789"
      }
    }
  }'

列出作业：

curl -X POST http://服务地址/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "list_jobs",
      "arguments": {
        "page_size": 10
      }
    }
  }'

取消作业：

curl -X POST http://服务地址/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: 您的API密钥" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "cancel_job",
      "arguments": {
        "job_id": "123456789"
      }
    }
  }'

MCP 工具列表

工具名称	说明
submit_batch_job	提交批量推理作业
get_job_status	查询作业状态
list_jobs	列出批量作业
cancel_job	取消作业

11 KiB Raw Blame History Unescape Escape

GCP 批量推理 Agent 使用指南

概述

快速开始

第一步：授权存储桶访问

第二步：准备输入文件

第三步：上传输入文件

第四步：提交批量作业

API 接口说明

1. 提交批量作业

2. 查询作业状态

3. 列出作业

4. 取消作业

作业状态说明

获取输出结果

支持的模型

常见问题

1. 403 Permission Denied

2. 404 Not Found

3. 400 Invalid Request

4. 作业长时间处于 PENDING 状态

计费说明

最佳实践

MCP 接口

MCP 端点

获取工具列表

调用工具

MCP 工具列表

11 KiB

Raw Blame History