ب راه‌اندازی AWS Bedrock

هدف یادگیری: یک workload Claude کامل (شامل streaming، tool use، Guardrails) روی Bedrock بالا بیاورید.

مفاهیم کلیدی: boto3, InvokeModel, InvokeModelWithResponseStream, Converse API, Cross-Region Inference Profile, IAM, Provisioned Throughput, Guardrails

۶.ب.۱ مفهوم: Claude on Bedrock چیست؟

Amazon Bedrock یک gateway مدیریت‌شده برای foundation models است. وقتی Claude را روی Bedrock صدا می‌زنید، تفاوت‌ها با native عبارت‌اند از:

• احراز هویت: AWS SigV4 (یا از اواخر ۲۰۲۵، Bedrock bearer tokens) به‌جای header x-api-key.
• Billing: روی فاکتور AWS، نه کنسول Anthropic.
• Data residency: تابع region AWS و BAA/compliance posture آمازون.
• دو سطح API هم‌زمان زنده‌اند: 1. مسیر raw model: InvokeModel و Converse روی سرویس bedrock-runtime، با model IDهای ARN-versioned مثل anthropic.claude-opus-4-6-v1. 2. مسیر Messages-API Bedrock endpoint: همان Anthropic Messages API روی مسیر /anthropic/v1/messages، که زیرش Bedrock اجرا می‌کند ولی با شکل JSON و SSE بومی Anthropic صحبت می‌کند.

این فصل بر مسیر legacy (یعنی InvokeModel/Converse) تمرکز دارد، چون اکثر مشتریان AWS-shop به‌صورت پیش‌فرض همان را استفاده می‌کنند. در پایان، به مسیر Messages-API هم اشاره می‌کنیم.

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

پیش‌نیاز: یک حساب AWS با billing فعال.

گام ۱ — نصب AWS CLI (نسخه >= 2.13.23):

# macOS
brew install awscli
# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install

گام ۲ — پیکربندی credentials:

aws configure          # sets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, region
aws sts get-caller-identity   # verify

گام ۳ — اشتراک مدل‌های Anthropic. در کنسول Bedrock به مسیر Model Access بروید و برای هر خانواده Claude که می‌خواهید درخواست دسترسی بدهید. از سال ۲۰۲۶ به بعد (طبق AWS Security Blog) مدل‌های serverless در هر region به‌صورت خودکار فعال می‌شوند و صفحه دستی «request access» برای بسیاری از SKUها بازنشسته شده — اما پذیرش EULA Marketplace برای فعال‌سازی اولیه Anthropic هنوز لازم است.

گام ۴ — نصب SDK. سه گزینه رسمی دارید:

# Anthropic SDK (recommended for parity with native API code)
pip install -U "anthropic[bedrock]"
npm install @anthropic-ai/bedrock-sdk

# Pure AWS SDK (boto3 / aws-sdk-js v3)
pip install "boto3>=1.28.59"
npm install @aws-sdk/client-bedrock-runtime

اگر در فصل ۴ کد Python نوشتید، anthropic[bedrock] بهترین انتخاب است — همان interface، فقط با تعویض client class.

گام ۵ — تایید مدل‌های موجود:

aws bedrock list-foundation-models --region us-west-2 \
  --by-provider anthropic \
  --query "modelSummaries[*].modelId"

گام ۶ — اولین درخواست. کد کامل در ۶.ب.۵ آمده است.

۶.ب.۳ مجوزهای IAM (least privilege)

حداقل policy برای فراخوانی Claude (on-demand، بدون provisioned throughput، در صورت اشتراک قبلی Marketplace):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "InvokeClaudeModels",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-*",
        "arn:aws:bedrock:*:*:inference-profile/*anthropic.claude-*"
      ]
    },
    {
      "Sid": "DiscoverModels",
      "Effect": "Allow",
      "Action": [
        "bedrock:ListFoundationModels",
        "bedrock:ListInferenceProfiles",
        "bedrock:GetFoundationModel"
      ],
      "Resource": "*"
    }
  ]
}

نکات حیاتی:

• برای Cross-Region Inference (CRIS)، خط دوم Resource اجباری است — درخواست به ARN از نوع inference-profile/... می‌خورد، نه به foundation-model/... خام. خیلی از کاربران تازه‌کار CRIS دقیقاً اینجا با AccessDeniedException برخورد می‌کنند چون فقط resource دوم را اضافه نکرده‌اند.
• برای فعال‌سازی اولیه Anthropic روی یک حساب تازه، aws-marketplace:Subscribe و aws-marketplace:ViewSubscriptions را هم به policy اضافه کنید.
• برای provisioned throughput، یک statement جدا با scope روی ARN provisioned-model/... بنویسید.
• برای batch inference، علاوه بر این، نیاز به bedrock:CreateModelInvocationJob، bedrock:GetModelInvocationJob، iam:PassRole (به نقش سرویس batch)، و دسترسی S3 read/write روی bucketهای ورودی/خروجی دارید.

۶.ب.۴ Model ID و جدول region (به‌روز ۲۰۲۶-۰۷)

Cross-Region Inference Profile — کافی است پیشوند geo و یک نقطه قبل از model ID بگذارید:

• Global: global.anthropic.claude-opus-4-6-v1:0 (پیش‌فرض برای Sonnet 4.5+ و Opus 4.6)
• نکته: AWS Bedrock معمولاً model ID را با snapshot date و suffix -vN:0 منتشر می‌کند. شناسه‌های دقیق روز را از AWS Bedrock model IDs page تأیید کنید.
• US: us.anthropic.claude-sonnet-4-5-20250929-v1:0 (پوشش us-east-1، us-east-2، us-west-2)
• EU: eu.anthropic.claude-sonnet-4-5-20250929-v1:0 (Frankfurt، Ireland، Paris، Zurich)
• APAC: apac.anthropic.claude-sonnet-4-20250514-v1:0 (Tokyo، Sydney، Singapore، Mumbai، Seoul)
• JP: jp.anthropic.claude-sonnet-4-5-20250929-v1:0 (Tokyo، Osaka)

endpointهای regional و multi-region برای Sonnet 4.5+ و Opus 4.6+ یک +۱۰٪ premium نسبت به global دارند. مدل‌های قدیمی‌تر همان قیمت تک-region قبلی را حفظ می‌کنند.

۶.ب.۵ نمونه‌های کد — مسیر InvokeModel

Python با anthropic[bedrock] — نزدیک‌ترین تجربه به فصل ۴؛ فقط client class و model ID عوض می‌شود.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(
    aws_access_key="<access key>",
    aws_secret_key="<secret key>",
    aws_session_token="<session_token>",   # for STS / SSO sessions
    aws_region="us-west-2",
)

message = client.messages.create(
    model="global.anthropic.claude-opus-4-6-v1",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello, world"}],
)
print(message.content)

Python با boto3 — سطح پایین‌تر؛ به فیلد anthropic_version در body دقت کنید (مخصوص Bedrock است) و body باید JSON-bytes باشد.

import boto3, json

bedrock = boto3.client(service_name="bedrock-runtime")
body = json.dumps({
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello, world"}],
    "anthropic_version": "bedrock-2023-05-31",
})
response = bedrock.invoke_model(
    body=body,
    modelId="global.anthropic.claude-opus-4-6-v1",
)
print(json.loads(response["body"].read())["content"])

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

import AnthropicBedrock from "@anthropic-ai/bedrock-sdk";

const client = new AnthropicBedrock({
  awsAccessKey: "<access key>",
  awsSecretKey: "<secret key>",
  awsSessionToken: "<session_token>",
  awsRegion: "us-west-2",
});

const message = await client.messages.create({
  model: "global.anthropic.claude-opus-4-6-v1",
  max_tokens: 256,
  messages: [{ role: "user", content: "Hello, world" }],
});
console.log(message);

Streaming با boto3 — از invoke_model_with_response_stream استفاده کنید؛ stream یک رشته از frameهای SSE-style است که در event["chunk"]["bytes"] با کدگذاری JSON قرار می‌گیرند.

resp = bedrock.invoke_model_with_response_stream(
    modelId="global.anthropic.claude-opus-4-6-v1",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Stream a haiku"}],
    }),
)
for event in resp["body"]:
    chunk = json.loads(event["chunk"]["bytes"])
    if chunk["type"] == "content_block_delta":
        print(chunk["delta"]["text"], end="", flush=True)

۶.ب.۶ Converse API — سطح یکپارچه

Converse API، surface چت provider-agnostic آمازون است. کد Converse را یک‌بار می‌نویسید، فقط modelId را عوض می‌کنید، و می‌توانید Llama، Mistral، Cohere و Claude را با همان شکل پارامترها صدا بزنید. اگر تیم شما Bedrock-only است، Converse گزینه پیش‌فرض پیشنهادی است.

Python boto3 — Converse پایه:

response = bedrock_client.converse(
    modelId="anthropic.claude-3-sonnet-20240229-v1:0",
    messages=[{"role": "user",
               "content": [{"text": "Create a list of 3 pop songs."}]}],
    system=[{"text": "You are an app that creates playlists..."}],
    inferenceConfig={"temperature": 0.5},
    additionalModelRequestFields={"top_k": 200},
)
print(response["output"]["message"]["content"][0]["text"])
print(response["stopReason"], response["usage"])

شکل پاسخ:

{
  "output": { "message": { "role": "assistant",
                           "content": [{"text": "..."}] } },
  "stopReason": "end_turn",
  "usage": { "inputTokens": 123, "outputTokens": 456, "totalTokens": 579 }
}

Streaming با ConverseStream:

resp = bedrock_client.converse_stream(
    modelId=model_id,
    messages=messages,
    system=system_prompts,
    inferenceConfig=inference_config,
)
for event in resp["stream"]:
    if "contentBlockDelta" in event:
        print(event["contentBlockDelta"]["delta"]["text"], end="")
    elif "messageStop" in event:
        print("\nStop reason:", event["messageStop"]["stopReason"])
    elif "metadata" in event:
        usage = event["metadata"].get("usage", {})
        print("tokens:", usage)

Multimodal (image / document / video) — Converse هر سه نوع را زیر یک taxonomy واحد content block جا می‌دهد:

message = {"role": "user", "content": [
    {"text": "What's in this image?"},
    {"image": {"format": "jpeg", "source": {"bytes": image_bytes}}},
]}
response = bedrock_client.converse(modelId=model_id, messages=[message])

برای document از {"document": {"name": "...", "format": "pdf", "source": {"bytes": ...}}} و برای video از {"video": {"format": "mp4", "source": {"bytes": ...}}} با همین الگو استفاده کنید.

Converse در برابر InvokeModel — کدام را انتخاب کنیم؟

۶.ب.۷ Bedrock Guardrails

Guardrails مقابل مدل می‌نشینند و هم prompt ورودی و هم completion خروجی را بازرسی می‌کنند. شش نوع policy:

1. Content filters — hate / insults / sexual / violence / misconduct / prompt-attack، با شدت قابل پیکربندی.
2. Denied topics — توضیح زبان‌طبیعی موضوعات ممنوع.
3. Word filters — لیست سیاه exact-string (مثل واژگان رکیک، نام رقبا).
4. Sensitive information / PII filters — مسدود یا mask (regex + احتمالاتی).
5. Contextual grounding checks — پاسخ‌هایی که از منبع RAG منحرف می‌شوند علامت می‌خورند.
6. Automated reasoning checks — اعتبارسنجی در برابر بسته قواعد منطقی.

اتصال Guardrail به Converse:

response = bedrock_client.converse(
    modelId="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    messages=[{"role": "user", "content": [{"text": user_input}]}],
    guardrailConfig={
        "guardrailIdentifier": "abcdefg12345",
        "guardrailVersion": "1",
        "trace": "enabled",
    },
)
# A blocked response surfaces as stopReason="guardrail_intervened"

می‌توانید ApplyGuardrail را به‌صورت standalone هم صدا بزنید (بدون فراخوانی مدل) تا یک رشته را در مقابل یک guardrail اعتبارسنجی کنید — مفید برای فیلتر کردن خروجی toolها.

۶.ب.۸ قیمت و throughput

دو حالت billing:

• On-demand (پرداخت به‌ازای token، بدون تعهد، پیش‌فرض).
• Provisioned Throughput (Model Units؛ ظرفیت ساعتی رزرو شده، نرخ per-token پایین‌تر، فقط روی endpointهای regional — روی global/CRIS در دسترس نیست).

نرخ‌های شاخص on-demand در Bedrock (به‌ازای ۱M token، region US/EU، سال ۲۰۲۶):

نکات:

• endpointهای regional/multi-region برای Sonnet 4.5+ و Opus 4.6+ یک +۱۰٪ نسبت به global دارند.
• Batch inference هزینه ورودی و خروجی را نصف می‌کند.
• Prompt caching روی Claude 3.5 Sonnet v2 و جدیدتر پشتیبانی می‌شود؛ cache write حدود ۲۵٪ گران‌تر از input تازه است، cache read حدود ۱۰٪ input.

۶.ب.۹ ابزارهای Bedrock-native کنار Claude

Bedrock یک toolbox AWS-native غنی دور Claude بسته‌بندی می‌کند که در نسخه native API نیست:

• Bedrock Knowledge Bases — RAG مدیریت‌شده. به S3 اشاره می‌کنید، Bedrock chunk می‌کند، با Titan/Cohere embed می‌کند، در OpenSearch Serverless / Pinecone / Aurora ذخیره می‌کند. Claude از طریق RetrieveAndGenerate در دسترس است.
• Bedrock Agents — orchestrator مدیریت‌شده tool-use با action groups (Lambda) و یکپارچگی KB. مشابه Anthropic Managed Agents اما با طعم AWS.
• Bedrock Prompt Management — کاتالوگ promptهای نسخه‌دار با substitution متغیر و A/B testing.
• Bedrock Flows — سازنده visual workflow (LLM nodes + منطق شرطی + connectors).
• Bedrock Evaluations — jobهای ارزیابی مدل (LLM-as-judge یا انسانی).
• Model Invocation Logging — هر prompt/completion را در S3 یا CloudWatch می‌اندازد (Anthropic حداقل ۳۰ روز نگهداری توصیه می‌کند).

۶.ب.۱۰ احراز هویت با bearer token (مناسب corporate)

AWS_BEARER_TOKEN_BEDROCK را تنظیم کنید یا برنامه‌ای پاس بدهید — مفید وقتی تیم باید Bedrock مصرف کند بدون اینکه AWS credentials/IAM داشته باشد:

var client = new AnthropicBedrockClient(
    new AnthropicBedrockApiTokenCredentials {
        BearerToken = "your-bearer-token",
        Region = "us-east-1",
    });

در حال حاضر در SDKهای C#، Go و Java پشتیبانی می‌شود. Python/TypeScript/Ruby/PHP هنوز SigV4 استفاده می‌کنند.

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

• فراموش کردن خط inference-profile/... در policy IAM وقتی از CRIS استفاده می‌کنید.
• فرستادن payload InvokeModel بدون فیلد anthropic_version (که Bedrock-specific است) — درخواست با خطا برمی‌گردد.
• خرید Provisioned Throughput روی یک endpoint global — پشتیبانی نمی‌شود؛ فقط regional.