# petaV3 云 GPU 内部 AI 工程实施 SOP

版本：v1.1

日期：2026-08-06

适用对象：petaV3 工程师、DevOps、AI infra 负责人
目标：把云 GPU 上的开源模型接入 petaV3，形成可测试、可回滚、可监控的 `internal_ai` provider。

## 1. SOP 目标

这份 SOP 不是商业计划书，而是工程执行文件。它回答：

1. 云 GPU server 要怎么准备。
2. vLLM / Qwen 模型要怎么部署。
3. AI Gateway 要怎么保护模型 API。
4. petaV3 要怎么新增 `internal_ai` provider。
5. 第一个业务功能要怎么迁移。
6. RAG 后续要怎么接。
7. 上线前要检查什么。
8. 出问题怎么 debug 和 rollback。

第一版只覆盖文本 AI。视频生成、图片生成、TTS、本地转录模型不在本 SOP 的第一阶段范围内。

## 2. 总体架构

```text
petaV3 Laravel / Vue
  |
  | AiClient -> internal_ai provider
  v
AI Gateway / Nginx
  |
  | OpenAI-compatible API
  v
vLLM Model Server
  |
  +-- Qwen / other open-weight model
  +-- NVIDIA GPU runtime
  +-- Docker
  |
  v
Qdrant Vector DB  (Phase 1 RAG)
```

## 3. 推荐执行顺序

| 顺序 | 工作 | 负责人 | 验收 |
|---|---|---|---|
| 1 | 申请云 GPU server | Infra | `nvidia-smi` 正常 |
| 2 | 安装 Docker + NVIDIA runtime | Infra | Docker container 可访问 GPU |
| 3 | 部署 vLLM + Qwen | Infra / AI Engineer | `/v1/chat/completions` 正常 |
| 4 | 部署 AI Gateway | Infra | API key / IP allowlist 生效 |
| 5 | petaV3 新增 `internal_ai` provider | Backend | provider test 成功 |
| 6 | 迁移第一个业务功能 | Backend / Business | 真实样本可跑 |
| 7 | 加日志、评测、成本记录 | Backend / Infra | POC report 可生成 |
| 8 | Phase 1 再接 RAG | Backend / Data | 私有数据可检索 |

## 4. 云 GPU Server 准备

### 4.1 建议配置

| 项目 | POC 建议 | 备注 |
|---|---|---|
| 云与地域 | 阿里云国际站，吉隆坡 `ap-southeast-3` 优先 | 新加坡 `ap-southeast-1` 仅作库存 / 能力备选 |
| 首选 GPU | `ecs.gn8is.2xlarge`，L20 48GB | 官方规格为 8 vCPU、64 GiB、1 张 L20；下单前检查实时库存 |
| 备选 GPU | A10 24GB 级实例 | 运行经过验证的 Qwen3-14B AWQ；不能默认同地域有货 |
| Disk | 300-500GB ESSD，加密 | 模型 cache、logs；Qdrant 在 Phase 1 再按容量扩展 |
| OS | Ubuntu 22.04 LTS | 首轮固定一个 OS 版本，避免环境变量过多 |
| Network | VPC；443 只允许 petaV3 来源 | SSH 仅 bastion / VPN / 固定 IP，8000 不开放 |

吉隆坡属于 Global Data Plane，不是中国大陆数据区。CN-test 只能使用合成或获批脱敏数据；真实大陆客户数据要在独立大陆区域、账号和合规评审完成后接入。

### 4.2 账号、预算与下单前置门

```text
[ ] 使用公司阿里云国际站账号，不使用个人账号
[ ] 创建最小权限 RAM 运维用户，MFA 已开启
[ ] POC 云支出硬上限为 USD 500
[ ] 50% / 80% / 100% 预算告警已配置并测试
[ ] 保存创建当日 calculator / order 报价和实例库存截图
[ ] 明确磁盘、快照、EIP 在 GPU 停机后仍可能继续计费
[ ] 记录 primary=Kuala Lumpur、fallback=Singapore 的批准人和理由
```

### 4.3 服务器初始化 checklist

```text
[ ] SSH key 已配置
[ ] root login 策略确认
[ ] 防火墙已限制 SSH 来源 IP
[ ] server timezone 已确认
[ ] disk size 足够
[ ] GPU 可见
[ ] Docker 可运行
[ ] Docker 可访问 GPU
```

### 4.4 GPU 验证命令

```bash
nvidia-smi
```

预期：

```text
能看到 GPU 型号、显存、driver version、CUDA version。
```

Docker GPU 验证：

```bash
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
```

预期：

```text
container 内也能看到同一张 GPU。
```

### 4.5 非工作时段节费停机

必须通过 OOS 定时任务或 ECS API 调用 `StopInstance`，并设置 `StoppedMode=StopCharging`。Linux 内执行 `shutdown`、`poweroff` 或 `halt` 不会触发阿里云节省停机模式。

验收：

```text
[ ] 工作日开机 / 停机窗口由 OOS 或受控 API 管理
[ ] 停机后控制台显示节省停机模式，而不是普通 OS 关机
[ ] 账单中已区分释放的 GPU/CPU/RAM 与继续计费的磁盘/EIP
[ ] runbook 记录恢复时可能因 GPU 库存不足而启动失败
[ ] 新加坡或替代 GPU 规格的应急步骤已写明
```

## 5. vLLM 模型服务部署

### 5.1 目录规划

建议：

```text
/opt/peta-ai/
  docker-compose.yml
  .env
  logs/
  models-cache/
  qdrant/
```

### 5.2 第一版模型选择

| 模型 | 适合用途 | 建议 |
|---|---|---|
| Qwen 7B | 快速 smoke test | 低成本测试 |
| Qwen3-14B BF16 | L20 首轮业务 POC | structured extraction 推荐起点 |
| Qwen3-14B AWQ | A10 24GB 备选 | 上线前必须与 BF16 做质量对照 |
| Qwen 32B quantized | 后续更高质量分析 | 只有 14B 不能达标时再测 |

第一版从 Qwen3-14B 开始，先验证预算、异议、偏好、意图、next action 等结构化字段。WhatsApp 中英双语语气另外与现有 frontier provider 比较，不能用 draft 的单一总分否定结构化抽取 POC。

### 5.3 vLLM Docker 启动示例

```bash
docker run -d \
  --name peta-ai-vllm \
  --runtime nvidia \
  --gpus all \
  -v /opt/peta-ai/models-cache:/root/.cache/huggingface \
  -p 127.0.0.1:8000:8000 \
  --ipc=host \
  --restart unless-stopped \
  vllm/vllm-openai:<PINNED_TAG>@sha256:<APPROVED_DIGEST> \
  --model Qwen/Qwen3-14B \
  --revision <PINNED_MODEL_REVISION> \
  --served-model-name peta-qwen3-14b \
  --api-key "<VLLM_SERVICE_KEY>" \
  --host 0.0.0.0 \
  --port 8000
```

注意：

- `-p 127.0.0.1:8000:8000` 表示只绑定本机，避免直接公网访问。
- 公开访问应通过 AI Gateway / Nginx。
- `<PINNED_TAG>`、digest、model revision 和 key 必须由 deployment manifest / secret manager 注入，不能原样执行或提交到 git。
- 正式 POC 禁止浮动 `latest`；模型 revision、tokenizer revision 和量化文件 checksum 必须留档。

### 5.4 API 测试

在 GPU server 上测试：

```bash
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <VLLM_SERVICE_KEY>" \
  -d '{
    "model": "peta-qwen3-14b",
    "messages": [
      {"role": "user", "content": "Summarize what a real estate sales copilot should do."}
    ]
  }'
```

验收：

```text
[ ] API 有返回
[ ] response 包含 assistant message
[ ] 简单问题 3-10 秒内返回
[ ] vLLM logs 无 OOM
```

## 6. AI Gateway / Nginx

### 6.1 为什么需要 Gateway

petaV3 不应该直接访问裸 vLLM。Gateway 负责：

1. API key 验证。
2. IP allowlist。
3. HTTPS。
4. rate limit。
5. timeout。
6. access log。
7. 后续 model routing。

### 6.2 最小 Nginx 逻辑

```text
client -> https://ai.company.com/v1/chat/completions
  -> Nginx checks API key and IP
  -> proxy_pass http://127.0.0.1:8000
```

### 6.3 Gateway 验收

```text
[ ] 没有 API key 返回 401/403
[ ] 错误 API key 返回 401/403
[ ] 非 allowlist IP 不能访问
[ ] petaV3 server 可以访问
[ ] access log 有记录
[ ] vLLM 8000 端口不直接公网暴露
[ ] 使用有效 CA 证书或私网 mTLS
[ ] petaV3 客户端保持 TLS verify=true
[ ] 没有用自签证书 + verify=false 绕过证书检查
```

## 7. petaV3 `internal_ai` Provider 接入

### 7.1 现有 AI 架构

petaV3 当前 AI 调用链：

```text
Business feature
  -> AiClient
  -> AiCredential / provider config
  -> Transport
  -> Provider API
  -> AiResponse
  -> ai_requests log
```

要重点理解：

```text
src/Ai/Services/AiClient.php
src/Ai/AiCredential.php
src/Ai/Transports/*
src/Ai/Responses/AiResponse.php
config/ai_prompts.php
```

### 7.2 internal_ai 设计

`internal_ai` 应该表现得像一个 OpenAI-compatible provider：

```text
provider: internal_ai
base_url: https://ai.company.com/v1
api_key: company internal key
model: Qwen/Qwen3-14B
transport: OpenAI-compatible
```

### 7.3 需要改动的地方

具体文件以实际代码为准，预计涉及：

| 区域 | 工作 |
|---|---|
| AiCredential provider catalog | 增加 `internal_ai` |
| AI provider settings UI | 允许配置 internal_ai key / model |
| Transport | 复用 OpenAI transport 或新增 InternalAiTransport |
| Model list | 增加内部模型列表 |
| Provider test | 支持调用 internal_ai |
| config | 增加 base URL / default model |
| tests | provider validation、test request、AiClient response |

### 7.4 Provider test 验收

```text
[ ] 后台可以保存 internal_ai
[ ] provider test 返回 OK
[ ] ai_requests 记录 provider=internal_ai
[ ] bad key 有错误提示
[ ] timeout 有错误提示
[ ] 可以切换回 Gemini / OpenAI
```

## 8. 第一个业务试点接入

### 8.1 推荐优先级

| 优先级 | 功能 | 原因 |
|---|---|---|
| 1 | ConversationAnalyzer | 结构化抽取最适合验证 14B 模型和房地产标签价值 |
| 2 | AI Conversations | 用于补充 chat / stream 技术验证，不作为唯一商业证据 |
| 3 | WhatsApp draft | 商业价值高，但先 human review |

### 8.2 ConversationAnalyzer 试点步骤

1. 从更大的已授权样本池中冻结 20-50 条 blind evaluation transcript，prompt 调优后不得替换难例。
2. 标注预算、异议、偏好、意图、next action，并连接 appointment、viewing、booking、SPA、won/lost 等已知结果；未知结果记为 `unknown`。
3. 用现有 provider 跑一次并保存版本化输出。
4. 用 `internal_ai` 跑一次并保存版本化输出。
5. 对比 JSON 稳定性和字段级 precision / recall / F1。
6. 让至少两名业务评测人独立评分并处理分歧。
7. 记录 latency、错误率、人工修正和每任务成本。

验收：

```text
[ ] 能输出完整 schema
[ ] 能提取预算、意图、偏好、痛点
[ ] next action 可执行
[ ] JSON/schema success >= 95%
[ ] 关键字段人工准确率 >= 85%，且不低于当前 provider 基线
[ ] blind evaluation set 的已知结果标签完整率 >= 90%
[ ] 严重 hallucination / 数据泄漏 = 0
```

### 8.3 WhatsApp draft 注意事项

第一版必须 draft，不要 auto-send。

原因：

- 避免错误承诺。
- 避免语气不合适。
- 避免 WhatsApp 风控。
- 方便统计人工修改率。

记录 `shown / accepted / edited / sent / dismissed / executed`。edit rate 超过 50% 不单独触发 No-Go；高风险承诺必须为 0，且第一版不得自动发送。

## 9. RAG Phase 1 接入

### 9.1 第一批数据

```text
call_recordings.transcript
customer_journey_reports
whatsapp_messages
leads
property_analyses
wealth_plans
video_projects.brief
video_projects.chat_state
```

### 9.2 Qdrant collection 建议

第一版可以一个 collection：

```text
collection: peta_v3_documents
vector_size: depends on embedding model
distance: cosine
```

payload：

```json
{
  "source_type": "call_transcript",
  "source_id": 123,
  "lead_id": 456,
  "admin_id": 789,
  "user_id": null,
  "company_id": "propertylab",
  "created_at": "2026-07-08",
  "permission_scope": "sales_team",
  "title": "Call transcript with Lead #456"
}
```

### 9.3 RAG 权限原则

不能只靠 prompt 叫 AI 不泄漏数据，必须 server-side filter。

流程：

```text
User asks question
  -> petaV3 resolves user's allowed lead/team/company scope
  -> Qdrant search with metadata filter
  -> retrieved chunks filtered again in Laravel
  -> only allowed context sent to model
```

验收：

```text
[ ] 普通销售查不到其他销售的 lead
[ ] manager 可查 team 数据
[ ] admin 可查全局数据
[ ] 外部客户数据 collection 完全隔离
```

## 10. 日志、监控和成本

### 10.1 必须记录

```text
provider
model
prompt key
subject type / id
lead id
request duration
status
error
input token estimate
output token estimate
retrieved document ids
```

### 10.2 GPU 监控

最小指标：

```text
GPU utilization
VRAM usage
request count
latency p50 / p95
error rate
OOM count
container restart count
```

### 10.3 成本记录

每天记录：

```text
GPU hourly cost
running hours
request count
average latency
estimated cost per request
disk / snapshot / EIP continuing cost
budget consumed percentage
```

POC 云支出超过 USD 500 时停止新增实验并由项目负责人复核。工程、标注和业务评测工时单独报告，不能混入 GPU 单价。

## 11. 安全上线 Checklist

```text
[ ] vLLM 没有直接公网暴露
[ ] Gateway 已强制 API key
[ ] Gateway 已限制 IP
[ ] HTTPS 已配置
[ ] TLS verify=true，没有自签证书绕过
[ ] vLLM image tag + digest、model revision 已固定
[ ] OOS / ECS API 节省停机已验证，未使用 Linux shutdown 代替
[ ] USD 500 预算和告警已生效
[ ] petaV3 secret 不在 git
[ ] ai_requests 不记录 API key
[ ] RAG 检索有权限过滤
[ ] WhatsApp 只启用 draft mode
[ ] fallback 符合区域 policy；CN 不自动回退到 Global provider
[ ] 有 timeout 设置
[ ] 有错误提示
[ ] 有日志可 debug
```

## 12. Debug Checklist

### 12.1 vLLM 没响应

检查：

```bash
docker ps
docker logs peta-ai-vllm --tail 200
nvidia-smi
curl http://127.0.0.1:8000/v1/models
```

可能原因：

- 模型没加载完。
- GPU OOM。
- container crash。
- port 没绑定。

### 12.2 petaV3 调不到模型

检查：

```text
base_url 是否正确
API key 是否正确
Gateway 是否 allowlist petaV3 server IP
Nginx access log
petaV3 laravel.log
ai_requests error
```

### 12.3 JSON 输出失败

处理：

```text
降低 temperature
增强 schema prompt
增加 retry
增加 validator
保留 fallback provider
```

### 12.4 模型回答质量差

处理：

```text
调整 prompt
换更大模型
加入 RAG context
增加 few-shot examples
对比 Gemini 输出
让业务方给具体差评原因
```

## 13. Rollback 策略

任何业务功能接 internal_ai 时，都必须可回滚：

```text
feature config: provider=internal_ai
rollback: provider=gemini/openai
```

上线原则：

1. 不直接删除原 provider。
2. 每个业务功能独立切换。
3. 先 internal users。
4. 再 small group。
5. 最后才扩大。

## 14. 完成定义

本 SOP 的第一阶段完成标准：

```text
[ ] 云 GPU 模型 API 可稳定运行
[ ] petaV3 internal_ai provider 可配置
[ ] provider test 成功
[ ] 至少一个业务功能可调用 internal_ai
[ ] ai_requests 有完整日志
[ ] latency / error / cost 可统计
[ ] 有 fallback 和 rollback
[ ] 有 POC 评测数据
```

完成后进入 Phase 1：RAG、更多业务接入、内部 case study。

## 15. 官方参考资料

- 阿里云地域代码：<https://www.alibabacloud.com/help/en/user-center/developer-reference/common-region-id-reference>
- 阿里云 gn8is / L20 GPU 实例规格：<https://www.alibabacloud.com/help/en/ecs/user-guide/gpu-accelerated-compute-optimized-and-vgpu-accelerated-instance-families-1>
- 阿里云 ECS 节省停机模式：<https://www.alibabacloud.com/help/en/ecs/user-guide/economical-mode>
- vLLM OpenAI-compatible server：<https://docs.vllm.ai/en/latest/serving/online_serving/openai_compatible_server/>
- vLLM Docker 部署：<https://docs.vllm.ai/en/latest/deployment/docker/>