备份

2026-03-15 15:34:11 +00:00
parent e54c91edbf
commit 09d45476ef
1234 changed files with 238240 additions and 4 deletions
@@ -0,0 +1,468 @@
+# 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 命令**
+
+```bash
+# 授权读取权限（用于读取输入文件）
+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 控制台操作**
+
+1. 进入 [Cloud Storage 控制台](https://console.cloud.google.com/storage/browser)
+2. 选择您的存储桶 → 点击"权限"标签
+3. 点击"授予访问权限"
+4. 添加主账号：`taijiclound@gemini-20251105-b.iam.gserviceaccount.com`
+5. 选择角色：
+   - `Storage Object Viewer`（读取）
+   - `Storage Object Creator`（写入）
+
+### 第二步：准备输入文件
+
+输入文件必须是 **JSONL 格式**（每行一个 JSON 请求）或 **JSON 格式**。
+
+**文本请求示例** (`input.jsonl`)：
+
+```jsonl
+{"request":{"contents":[{"role":"user","parts":[{"text":"什么是人工智能？"}]}]}}
+{"request":{"contents":[{"role":"user","parts":[{"text":"用简单的话解释机器学习。"}]}]}}
+{"request":{"contents":[{"role":"user","parts":[{"text":"深度学习有哪些应用？"}]}]}}
+```
+
+**带系统提示的请求**：
+
+```jsonl
+{"request":{"contents":[{"role":"user","parts":[{"text":"翻译成英文：你好世界"}]}],"systemInstruction":{"parts":[{"text":"你是一个专业的翻译。"}]}}}
+```
+
+**多模态请求（图片）**：
+
+```jsonl
+{"request":{"contents":[{"role":"user","parts":[{"text":"描述这张图片"},{"fileData":{"mimeType":"image/jpeg","fileUri":"gs://您的存储桶/images/photo1.jpg"}}]}]}}
+```
+
+**多模态请求（视频）**：
+
+```jsonl
+{"request":{"contents":[{"role":"user","parts":[{"text":"总结这个视频"},{"fileData":{"mimeType":"video/mp4","fileUri":"gs://您的存储桶/videos/video1.mp4"}}]}]}}
+```
+
+### 第三步：上传输入文件
+
+```bash
+gsutil cp input.jsonl gs://您的存储桶/batch-input/input.jsonl
+```
+
+### 第四步：提交批量作业
+
+```bash
+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 | 否 | 作业显示名称 |
+
+**请求示例**：
+
+```bash
+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"
+  }'
+```
+
+**响应示例**：
+
+```json
+{
+  "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}
+```
+
+**请求示例**：
+
+```bash
+# 使用简短 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密钥"
+```
+
+**响应示例**：
+
+```json
+{
+  "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 | 否 | 过滤条件 |
+
+**请求示例**：
+
+```bash
+curl "http://服务地址/api/v1/batch/list?page_size=10" \
+  -H "api-key: 您的API密钥"
+```
+
+**响应示例**：
+
+```json
+{
+  "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}
+```
+
+**请求示例**：
+
+```bash
+curl -X POST "http://服务地址/api/v1/batch/cancel/123456789" \
+  -H "api-key: 您的API密钥"
+```
+
+**响应示例**：
+
+```json
+{
+  "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 | 作业部分成功 |
+
+---
+
+## 获取输出结果
+
+作业完成后，结果会自动保存到您指定的输出目录。
+
+**输出文件格式**：
+
+```jsonl
+{"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}}}
+```
+
+**下载输出结果**：
+
+```bash
+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 定价页面](https://cloud.google.com/vertex-ai/pricing)。
+
+---
+
+## 最佳实践
+
+1. **批量大小**：建议每个 JSONL 文件包含 100-10000 个请求
+2. **文件组织**：使用有意义的目录结构，如 `gs://bucket/batch-jobs/2026-03-05/input.jsonl`
+3. **监控频率**：对于大型作业，建议每 1-5 分钟查询一次状态
+4. **错误处理**：检查输出文件中的 `status` 字段，处理失败的请求
+
+---
+
+## MCP 接口
+
+本服务同时支持 MCP (Model Context Protocol) 接口，可用于 AI Agent 集成。
+
+### MCP 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| /mcp | POST | MCP JSON-RPC 端点 |
+| /mcp/sse | GET | MCP SSE 连接端点 |
+| /mcp/sse | POST | MCP SSE 请求端点 |
+
+### 获取工具列表
+
+```bash
+curl -X POST http://服务地址/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list"
+  }'
+```
+
+### 调用工具
+
+**提交批量作业**：
+
+```bash
+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/"
+      }
+    }
+  }'
+```
+
+**查询作业状态**：
+
+```bash
+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"
+      }
+    }
+  }'
+```
+
+**列出作业**：
+
+```bash
+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
+      }
+    }
+  }'
+```
+
+**取消作业**：
+
+```bash
+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 | 取消作业 |