ج راه‌اندازی GCP Vertex AI

هدف یادگیری: یک workload Claude کامل (شامل streaming و multimodal) روی Vertex AI بالا بیاورید.

مفاهیم کلیدی: Vertex AI, Model Garden, gcloud, Application Default Credentials, :rawPredict, :streamRawPredict, anthropic[vertex]

۶.ج.۱ مفهوم: Claude on Vertex چیست؟

Vertex AI، پلتفرم ML یکپارچه Google Cloud است؛ Claude به‌عنوان یک partner model در Model Garden عرضه می‌شود. تفاوت‌ها با native Anthropic API:

• احراز هویت با Google ADC (Application Default Credentials) از طریق gcloud auth — بدون x-api-key.
• model در body درخواست نیست. به‌جای آن، بخشی از URL endpoint Vertex است.
• anthropic_version در body می‌نشیند (باید رشته دقیق "vertex-2023-10-16" باشد)، نه در HTTP header.
• Billing روی پروژه GCP می‌خورد؛ هزینه در فاکتور GCP در کنار BigQuery/GKE ظاهر می‌شود.
• دو HTTP endpoint: :rawPredict (پاسخ تک‌قطعه‌ای) و :streamRawPredict (SSE).
• Compliance: FedRAMP High، HIPAA-eligible، ISO، SOC 2.

۶.ج.۲ شش گام راه‌اندازی

گام ۱ — یک پروژه GCP بسازید یا انتخاب کنید که billing روی آن فعال باشد.

گام ۲ — فعال‌سازی Vertex AI API:

gcloud config set project MY_PROJECT_ID
gcloud services enable aiplatform.googleapis.com

گام ۳ — احراز هویت با ADC:

gcloud auth application-default login
# or, on a GCE/Cloud Run instance, attach a service account with the role below

گام ۴ — اشتراک Claude در Model Garden. در کنسول → Vertex AI → Model Garden → جست‌وجوی «Claude» → کلیک روی کارت مدل (مثلاً Claude Opus 4.8) → «Enable» → پذیرش شرایط Anthropic. این برای هر خانواده Anthropic انجام می‌شود، نه برای هر نسخه مدل.

گام ۵ — نصب SDK:

pip install -U google-cloud-aiplatform "anthropic[vertex]"
npm install @anthropic-ai/vertex-sdk

گام ۶ — تایید با یک smoke test (کد در ۶.ج.۵).

۶.ج.۳ نقش‌های IAM

حداقل نقش per-principal: roles/aiplatform.user (Vertex AI User). این نقش aiplatform.endpoints.predict و aiplatform.endpoints.streamRawPredict را با خود می‌آورد، که دقیقاً همان چیزی است که مسیر inference Claude نیاز دارد.

برای pipelines و service accounts، این‌ها را هم بدهید:

• roles/serviceusage.serviceUsageConsumer (برای اینکه اصلاً API را صدا بزنید).
• roles/logging.logWriter (اگر request-response logging را روشن می‌کنید).

یک نقش سفارشی least-privilege به این شکل:

title: ClaudeVertexInvoker
description: Invoke Anthropic Claude on Vertex AI
stage: GA
includedPermissions:
  - aiplatform.endpoints.predict
  - aiplatform.endpoints.streamRawPredict
  - aiplatform.endpoints.get
  - aiplatform.publisherModels.get
  - aiplatform.publisherModels.list

اتصال این نقش به یک service account:

gcloud projects add-iam-policy-binding MY_PROJECT_ID \
  --member="serviceAccount:my-app@MY_PROJECT_ID.iam.gserviceaccount.com" \
  --role="projects/MY_PROJECT_ID/roles/ClaudeVertexInvoker"

۶.ج.۴ Model ID، region، و URL endpoint

Vertex API model IDs (بدون پیشوند anthropic.؛ مدل‌های نسل فعلی ID ساده‌ی first-party دارند و فرم @YYYYMMDD فقط برای snapshotهای تاریخ‌دار است):

قالب URL endpoint:

# Streaming SSE
https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/anthropic/models/{MODEL_ID}:streamRawPredict

# Non-streaming
https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/anthropic/models/{MODEL_ID}:rawPredict

برای LOCATION=global، hostname خاص است: aiplatform.googleapis.com (بدون پیشوند region). برای multi-region (us، eu)، hostname به شکل aiplatform.{us|eu}.rep.googleapis.com است.

جدول دسترس‌پذیری region (الگوی معمول؛ مدل‌به‌مدل تغییر می‌کند — همیشه در Model Garden تایید کنید):

سه لایه endpoint، موازی با Bedrock:

• Global — مسیریابی پویا برای حداکثر در دسترس بودن، بدون premium، فقط pay-as-you-go (بدون provisioned throughput).
• Multi-region (us/eu) — مسیریابی پویای geography-pinned، +۱۰٪ premium، فقط pay-as-you-go.
• Regional — هارد-pin به یک region، +۱۰٪ premium، هم pay-as-you-go و هم provisioned throughput.

۶.ج.۵ نمونه‌های کد

curl (مرجع canonical):

MODEL_ID=claude-opus-4-8
LOCATION=global
PROJECT_ID=MY_PROJECT_ID

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://$LOCATION-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/anthropic/models/${MODEL_ID}:streamRawPredict \
  -d '{
    "anthropic_version": "vertex-2023-10-16",
    "messages": [{"role": "user", "content": "Hey Claude!"}],
    "max_tokens": 100
  }'

Python با anthropic[vertex]:

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="MY_PROJECT_ID", region="global")

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=100,
    messages=[{"role": "user", "content": "Hey Claude!"}],
)
print(message)

TypeScript با @anthropic-ai/vertex-sdk:

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const client = new AnthropicVertex({
  projectId: "MY_PROJECT_ID",
  region: "global",   // or "us", "eu", "us-east5", etc.
});

const result = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 100,
  messages: [{ role: "user", content: "Hey Claude!" }],
});
console.log(JSON.stringify(result, null, 2));

Streaming در Python:

with client.messages.stream(
    model="claude-opus-4-8",
    max_tokens=512,
    messages=[{"role": "user", "content": "Stream a haiku"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

۶.ج.۶ قیمت و billing

billing Claude روی Vertex همان شکل Bedrock را دارد:

• Pay-as-you-go به‌ازای ۱M token ورودی/خروجی (نرخ‌ها در cloud.google.com/vertex-ai/generative-ai/pricing).
• Provisioned Throughput — ظرفیت رزروشده در Generative AI Scale Units (GSUs) — فقط روی endpointهای regional.
• endpointهای regional/multi-region یک +۱۰٪ نسبت به global دارند (فقط Sonnet 4.5+). مدل‌های قدیمی‌تر قیمت regional flat قبلی را حفظ می‌کنند.
• Batch prediction از طریق batchPredictionJobs.create — معمولاً نصف قیمت (مطابق Bedrock batch).

هزینه روی فاکتور GCP تجمیع می‌شود و در Cloud Billing قابل مشاهده است؛ صفحه قیمت Anthropic ضرایب پلتفرم partner را مستند می‌کند.

۶.ج.۷ ابزارهای Vertex-native

• Model Garden — کشف، notebookهای نمونه، دکمه deploy.
• Vertex AI Agents / Reasoning Engine — runtime مدیریت‌شده agent.
• Vertex AI Search — RAG مدیریت‌شده (vector + keyword + reranker)؛ می‌تواند Claude را به‌عنوان generator صدا بزند.
• Pipelines (KFP) — orchestration؛ فراخوانی Claude به یک component تبدیل می‌شود.
• Request-response logging — sink اختیاری به BigQuery برای prompts/completions (Anthropic حداقل ۳۰ روز نگهداری توصیه می‌کند).
• VPC-SC — perimeter دور Vertex در پروژه شما؛ با Claude پشتیبانی می‌شود.

اشتباهات رایج روی Vertex

• گذاشتن model داخل body درخواست — Vertex از URL می‌خواند، body خراب می‌شود.
• فراموش کردن رشته دقیق "vertex-2023-10-16" در anthropic_version — یا اشتباه کپی کردن نسخه bedrock-2023-05-31 از Bedrock.
• استفاده از hostname معمولی برای multi-region: برای us و eu به aiplatform.us.rep.googleapis.com و aiplatform.eu.rep.googleapis.com نیاز دارید، نه us-aiplatform.googleapis.com.