Anthropic Claude 모델을 사용하는 빠른 모드

빠른 모드는 Gemini Enterprise Agent Platform에서 지원되는 Anthropic Claude 모델의 출력 토큰 생성을 가속화합니다. 기본 모델의 인텔리전스 및 안전 기능을 보존하는 고속 서빙 구성을 사용합니다. 요청 본문에 "speed": "fast"를 설정하여 온라인 예측 요청에서 빠른 모드를 사용 설정합니다.

토큰 생성을 기다리는 동안 개발자 또는 사용자 흐름이 중단되는 지연 시간에 민감한 대화형 워크로드에는 빠른 모드를 사용하세요.

• 대화형 에이전트형 코딩: 컨텍스트 전환 없이 휴먼인더루프 에이전트를 사용하여 다단계 코딩, 리팩터링, 디버깅 작업을 반복합니다.
• 실시간 계획: 저장소 또는 운영 컨텍스트를 수집하고 실행 계획을 대화형으로 생성합니다.
• 사고 대응: 추론 처리 시간이 중요한 경우 프로덕션 알림을 분류하고 해결 단계를 종합합니다.

지원되는 모델 및 수명 주기 정책

빠른 모드는 지원되는 Claude 모델 제품군의 최신 버전과 사용 중단되는 버전의 30일 전환 기간 동안 제공됩니다. Agent Platform은 다음 모델에 대해 빠른 모드를 지원합니다.

• Google Cloud의 Anthropic Claude Fable 5.2(claude-fable-5-2)

지원되는 모델 계열의 새 버전이 출시되면 해당 계열의 이전 버전에 대한 빠른 모드는 새 버전이 출시된 후 30일이 지나면 사용 중지됩니다. 30일의 사용 중단 기간이 종료된 후 "speed": "fast"이 포함된 이전 모델 버전에 대한 요청은 HTTP 400(INVALID_ARGUMENT) 오류를 반환합니다. 해당 모델 버전에 대한 표준 속도 요청은 계속 정상적으로 작동합니다. 빠른 모드를 계속 사용하려면 최신 모델 버전을 타겟팅하도록 요청을 업데이트하거나 요청 본문에서 "speed": "fast"를 삭제하세요.

지원되는 위치

빠른 모드는 지원되는 모델의 다음 API 위치 ID에서 사용할 수 있습니다.

• 전역(Google Cloud의 Anthropic Claude Fable 5.2): global
• 미국 멀티 리전(Google Cloud의 Anthropic Claude Fable 5.2): us
• 유럽 멀티 리전(Google Cloud의 Anthropic Claude Fable 5.2): eu

직접 리전 엔드포인트는 빠른 모드에서 공개적으로 지원되지 않습니다. 빠른 모드를 사용할 수 없는 위치에 "speed": "fast"를 사용하여 요청을 전송하면 HTTP 400(FAILED_PRECONDITION) 오류가 반환됩니다.

시작하기 전에

빠른 모드 요청을 보내기 전에 다음 설정 단계를 완료하세요. 빠른 모드는 표준 Claude 요청과 동일한 프로젝트 설정 및 Model Garden 사용 설정을 사용합니다. 추가 파트너 모델 설정 세부정보는 시작하기 전에를 참조하세요.

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

3. Verify that billing is enabled for your Cloud de Confiance project.

4. Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the API

5. 다음 Model Garden 모델 카드 중 하나로 이동하여 사용 설정을 클릭하고 모델별 약관 또는 데이터 공유 요구사항을 완료합니다.
   • Google Cloud에서 Anthropic의 Claude Fable 5.2로 이동

필요한 역할

Claude 모델에 빠른 모드 예측 요청을 전송하는 데 필요한 권한을 얻으려면 관리자에게 Cloud de Confiance by S3NS 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• 파트너 모델에 예측 요청 전송: Agent Platform 사용자(roles/aiplatform.user)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

빠른 모드 요청 전송

빠른 모드를 사용하려면 표준 게시자 모델 엔드포인트(예: claude-fable-5-2)에 요청을 보내고 최상위 요청 본문에 "speed": "fast"을 설정합니다. anthropic-beta 헤더가 필요하지 않으며 Model Garden에서 사용 설정할 별도의 모델 카드가 없습니다.

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict

{
  "anthropic_version": "vertex-2023-10-16",
  "speed": "fast",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Analyze the root cause of an HTTP 502 spike on an upstream GKE ingress controller and list three immediate mitigation steps."
    }
  ]
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

{
  "id": "msg_vrtx_01FastModeExample89ABcdEF",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5-2",
  "content": [
    {
      "type": "text",
      "text": "Here are the most common root causes for an HTTP 502 spike on a GKE Ingress controller and three immediate mitigation steps..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 34,
    "output_tokens": 218,
    "speed": "fast"
  }
}

from anthropic import AnthropicVertex
from anthropic.types import Message


def generate_with_fast_mode(
    project_id: str = "PROJECT_ID",
) -> Message:
    client = AnthropicVertex(
        project_id=project_id,
        region="global",
    )

    message = client.messages.create(
        model="claude-fable-5-2",
        max_tokens=1024,
        extra_body={"speed": "fast"},
        messages=[
            {
                "role": "user",
                "content": (
                    "Analyze the root cause of an HTTP 502 spike on an upstream "
                    "GKE ingress controller and list three immediate mitigation "
                    "steps."
                ),
            }
        ],
    )
    print(message.model_dump_json(indent=2))
    return message

사용된 속도 확인

응답의 usage.speed 필드를 검사하여 요청이 빠른 모드로 제공되었는지 확인할 수 있습니다.

• 빠른 모드: usage.speed가 있고 "fast"로 설정됩니다(단항 응답 또는 스트리밍 응답의 message_start 또는 message_delta 이벤트).
• 표준 속도: 표준 요청을 전송하면("speed": "standard" 또는 speed 생략) usage.speed는 "standard"이거나 생략됩니다.

할당량, 모니터링, 액세스 제어

빠른 모드는 표준 속도 트래픽과 격리된 전용 용량 및 비율 제한을 사용하는 한편 기본 모델에 대한 프로젝트의 액세스 구성을 상속합니다.

할당량

전역 및 멀티 리전 엔드포인트에서 빠른 모드 요청은 표준 속도 모델 할당량과 별도로 전용 공유 계보 할당량 버킷을 사용합니다. 빠른 모드 트래픽은 표준 anthropic-claude-fable 할당량에서 차감되지 않으며 표준 속도 트래픽은 빠른 모드 할당량에서 차감되지 않습니다.

Cloud de Confiance 콘솔의 할당량 및 시스템 한도 페이지에서 빠른 모드 할당량 상향을 보거나 요청하려면 base_model로 필터링합니다.

• anthropic-claude-fable-fast(전역 및 멀티 리전 엔드포인트에 적용)

소비 옵션 및 프로비저닝된 처리량

빠른 모드는 프로비저닝된 처리량을 지원하지 않습니다.

• 사용한 만큼만 지불만 해당: 프로젝트에 기본 모델에 대한 활성 프로비저닝된 처리량 주문이 있더라도 빠른 모드 요청은 항상 pay-as-you-go을 사용합니다. 빠른 모드 트래픽은 프로비저닝된 처리량 주문을 소비하거나 초과하지 않습니다.
• dedicated 요청 헤더가 제한됨: 빠른 모드 요청에 X-Vertex-AI-LLM-Request-Type: dedicated HTTP 헤더(또는 gRPC 메타데이터)를 포함하지 마세요. 빠른 모드에는 프로비저닝된 처리량 할당량이 없으며 dedicated 요청이 사용한 만큼만 지불로 넘어갈 수 없습니다. 따라서 X-Vertex-AI-LLM-Request-Type: dedicated가 있는 빠른 모드 요청은 HTTP 429(RESOURCE_EXHAUSTED) 오류를 반환합니다. 헤더를 생략하거나 대신 X-Vertex-AI-LLM-Request-Type: shared를 설정합니다.

빠른 모드 측정항목 모니터링

Cloud Monitoring에서 빠른 모드 트래픽은 기본 모델 ID(claude-fable-5-2)가 아닌 model_user_id="claude-fable-5-2-fast"를 보고합니다. 측정항목 탐색기에서 model_user_id="claude-fable-5-2-fast"로 필터링하여 표준 속도 트래픽과 별도로 빠른 모드의 요청 수, 토큰 사용량, 지연 시간을 모니터링합니다.

액세스 제어 및 조직 정책

빠른 모드는 기본 모델과 동일한 필수 역할 및 Model Garden 사용 설정 상태를 사용합니다. 요청에서 403 PERMISSION_DENIED가 반환되면 주 구성원에게 Agent Platform 사용자 역할(roles/aiplatform.user)이 있고 Model Garden에서 기본 모델이 사용 설정되어 있는지 확인합니다.

조직에서 constraints/vertexai.allowedModels 조직 정책 제약 조건을 적용하는 경우 빠른 모드는 기본 모델의 :predict 값(예: publishers/anthropic/models/claude-fable-5-2:predict)에 의거하여 제어됩니다.

• publishers/anthropic/models/claude-fable-5-2:predict을 허용하면 claude-fable-5-2에 대한 표준 속도 및 빠른 모드 요청이 모두 허용됩니다.
• publishers/anthropic/models/claude-fable-5-2:predict를 거부하면 표준 속도 및 빠른 모드 요청이 모두 차단됩니다.

조직 정책에 대한 자세한 내용은 Model Garden 모델에 대한 액세스 제어를 참조하세요.

가격 책정

빠른 모드는 항상 pay-as-you-go 결제를 사용하며 표준 속도 요청과 별도의 가격 책정이 적용됩니다.

• 토큰: 모든 토큰 유형(입력, 출력, 5분 및 1시간 캐시 쓰기, 캐시 적중 토큰)에서 표준 속도 토큰 요금의 2배로 가격이 책정됩니다.
• 웹 검색: 웹 검색 도구 호출은 표준(1x) 요율로 청구됩니다.

사용량은 빠른 모드 라벨이 지정된 기본 모델의 Cloud de Confiance by S3NS SKU로 청구됩니다. 리전 및 전역 토큰 요금은 Agent Platform 가격 책정 페이지를 참조하세요.

제한사항 및 오류 처리

빠른 모드를 사용할 때는 다음 제한사항에 유의하세요.

• 프로비저닝된 처리량 없음: 빠른 모드는 프로비저닝된 처리량을 지원하지 않으며 항상 사용한 만큼만 지불을 사용합니다. X-Vertex-AI-LLM-Request-Type: dedicated 헤더를 사용하여 빠른 모드 요청을 전송하면 HTTP 429(RESOURCE_EXHAUSTED) 오류가 반환됩니다.
• 일괄 예측 없음: 빠른 모드는 대화형 실시간 추론을 위해 설계되었으며 일괄 예측에서는 지원되지 않습니다.
• 프롬프트 캐시 격리: 프롬프트 캐시는 표준 속도 요청과 빠른 모드 요청 간에 공유되지 않습니다. 표준 속도로 작성된 캐시 항목은 빠른 모드에서 캐시 적중을 생성하지 않습니다. 마찬가지로 빠른 모드 캐시 항목은 표준 속도로 캐시 적중을 생성하지 않습니다.
• 자동 다운그레이드 없음: "speed": "fast"가 포함된 요청을 빠른 모드로 처리할 수 없는 경우 에이전트 플랫폼은 표준 속도로 대체하는 대신 오류를 반환합니다.

다음 표에는 잘못되었거나 지원되지 않는 빠른 모드 요청에 대해 반환되는 오류가 요약되어 있습니다.

빠른 모드 오류 처리

Agent Platform은 빠른 모드 요청을 자동으로 다운그레이드하지 않으므로 빠른 모드를 사용할 수 없을 때 어떻게 할지는 애플리케이션에서 결정합니다. 예를 들어 빠른 모드는 다음 버전이 출시된 후 30일이 지나면 사용 중지되거나 위치에서 빠른 모드를 제공하지 않을 수 있습니다. 다음 Python 샘플은 특정 빠른 모드 오류 메시지와 일치하므로 관련 없는 HTTP 400 오류가 계속 표시됩니다.

표준 속도로 대체

더 높은 지연 시간을 허용할 수 있는 워크로드의 경우 빠른 모드 가용성 오류를 포착하고 표준 속도로 요청을 다시 시도합니다.

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

# Errors that mean fast mode isn't available for this model or location.
_FAST_MODE_UNAVAILABLE = (
    "Fast mode (speed: fast) is not supported for this model.",
    "Fast mode is not available in this location.",
)


def generate_with_standard_fallback(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "claude-fable-5-2",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if not any(msg in str(e) for msg in _FAST_MODE_UNAVAILABLE):
            raise
        # Fast mode isn't available: retry at standard speed.
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
        )

다음을 바꿉니다.

• PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID(예: my-agent-project)
• LOCATION: 지원되는 위치(예: global)(기본값: global)
• PROMPT: 모델에 전송할 프롬프트 텍스트입니다.

다음 모델 버전으로 이동

모델 버전에서 사용 중지된 후에도 빠른 모드를 유지하려면 다음 버전에서 빠른 모드로 요청을 다시 시도하세요.

import anthropic
from anthropic import AnthropicVertex
from anthropic.types import Message

_FAST_MODE_NOT_SUPPORTED = (
    "Fast mode (speed: fast) is not supported for this model."
)


def generate_with_next_version(
    project_id: str = "PROJECT_ID",
    region: str = "LOCATION",
    model: str = "CURRENT_MODEL",
    next_model: str = "NEXT_MODEL",
) -> Message:
    client = AnthropicVertex(project_id=project_id, region=region)
    messages = [{"role": "user", "content": "PROMPT"}]
    try:
        return client.messages.create(
            model=model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )
    except anthropic.BadRequestError as e:
        if _FAST_MODE_NOT_SUPPORTED not in str(e):
            raise
        # Fast mode is retired on this version: use the next version.
        return client.messages.create(
            model=next_model,
            max_tokens=1024,
            messages=messages,
            extra_body={"speed": "fast"},
        )

다음을 바꿉니다.

• PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID(예: my-agent-project)
• LOCATION: 지원되는 위치(예: global)(기본값: global)
• CURRENT_MODEL 및 NEXT_MODEL: 사용하는 모델 버전(예: claude-fable-5-2)과 동일한 모델 계열의 다음 버전입니다.
• PROMPT: 모델에 전송할 프롬프트 텍스트입니다.

다음 버전 패턴은 모델 사용 중지 오류만 처리합니다. 위치에서 빠른 모드를 제공하지 않으면 다음 버전에서 오류가 해결되지 않습니다. 대신 요청을 지원되는 위치로 라우팅합니다.

다음 단계

• Claude 모델을 사용하여 예측 요청
• Anthropic Claude 모델 할당량
• 프롬프트 캐싱
• Model Garden 모델의 액세스 제어