라벨을 사용하여 generateContent, interactions.create, rawPredict와 같은 API 호출에 커스텀 메타데이터를 추가할 수 있습니다. 이 페이지에서는 라벨의 정의와 라벨을 사용하여 청구 요금을 분류하는 방법을 설명합니다.
라벨 정보
라벨은 generateContent, interactions.create, rawPredict와 같은 API 호출에 할당할 수 있는 키-값 쌍입니다. 라벨을 이용하면 이러한 호출을 구성하고 필요한 세부사항으로 규모에 맞게 사용량과 비용을 관리하는 데 도움이 됩니다. 각 호출에 라벨을 연결한 다음 해당 라벨을 기준으로 호출을 필터링할 수 있습니다. 라벨에 대한 정보는 사용량과 청구 요금을 라벨별로 분류할 수 있는 로깅 및 결제 시스템으로 전달됩니다. 기본 제공되는 결제 보고서를 통해 라벨별로 비용을 필터링하고 그룹화할 수 있습니다. 라벨을 사용하여 결제 데이터 내보내기를 쿼리할 수도 있습니다.
라벨을 만든 후 사용하는 방법에 대한 자세한 내용은 라벨 개요의 예를 참고하세요.
Agent Platform은 Cloud Billing에 도달하는 요청 본문 라벨과 추론 요청 메타데이터 로그에 표시되는 헤더 라벨이라는 두 가지 종류의 라벨을 지원합니다. 다음 섹션에서는 이 두 가지를 비교합니다.
사용 사례에 따라 라벨 선택
Agent Platform은 두 가지 라벨 메커니즘을 제공합니다. 설정 방식이 다르고, 도달하는 대상이 다르며, 추론 요청 메타데이터 로그의 다른 필드에 표시됩니다. 지원되는 경우 동일한 요청에서 둘 중 하나 또는 둘 다 사용할 수 있습니다.
요청 본문 라벨은 다음과 같이 작동합니다.
- 요청 본문의
labels필드에서 설정합니다. - Cloud Billing 및 추론 요청 메타데이터 로그에 도달합니다.
- 로그 항목의
labels필드에 표시됩니다. - 사용한 만큼만 지불 트래픽에서 지원됩니다.
- Claude와 같은 파트너 모델의 경우 요청 라벨은 요청 본문이 아닌
X-Vertex-AI-Labels헤더로 전송됩니다. Cloud Billing에 도달하지만 추론 요청 메타데이터 로그에 기록되지 않습니다.
헤더 라벨은 다음과 같이 작동합니다.
x-goog-agent-platform-observability-label-KEY요청 헤더에서 설정합니다.- 추론 요청 메타데이터 로그에만 도달합니다.
- 로그 항목의
jsonPayload.httpHeaders필드에 표시됩니다. - 지원되는 API 메서드: Gemini 모델의 경우
generateContent및streamGenerateContent, Claude 모델의 경우rawPredict및streamRawPredict지원되는 소비 옵션: 프로비저닝된 처리량 및 모델에서 제공하는 모든 사용한 만큼만 지불 옵션
로그 항목에서 각 라벨 찾기
단일 요청에 둘 다 포함될 수 있습니다. 다음 요청은 각각 하나씩 설정합니다.
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-pro:generateContent
x-goog-agent-platform-observability-label-team: payments
{
"labels": {"cost_center": "cc-1234"},
"contents": [{"role": "user", "parts": [{"text": "..."}]}]
}
두 라벨은 동일한 로그 항목의 서로 다른 필드에 표시됩니다.
{
"labels": {
"gen_ai.operation.name": "generate_content",
"cost_center": "cc-1234"
},
"jsonPayload": {
"httpHeaders": {
"x-goog-agent-platform-observability-label-team": {
"values": ["payments"]
}
}
}
}
두 라벨 유형은 서로 다른 필드를 차지하므로 쿼리하는 방식이 다릅니다. 로그 탐색기:
labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
Observability Analytics:
JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
["x-goog-agent-platform-observability-label-team"].values[0]) AS team
헤더 라벨 작동 방식
헤더 라벨은 추론 요청 메타데이터 로깅의 일부입니다. 이를 캡처하려면 프로젝트에 대해 추론 요청 메타데이터 로그를 사용 설정합니다.
예약된 프리픽스를 사용하여 라벨당 하나의 헤더를 전송합니다. 프리픽스는 대소문자를 구분하지 않습니다.
x-goog-agent-platform-observability-label-KEY: VALUE
예를 들면 다음과 같습니다.
x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr
각 헤더는 jsonPayload.httpHeaders 아래의 로그 항목에 표시되며, 소문자 헤더 이름으로 키가 지정되고 값은 values 배열에 있습니다(로그 항목에서 각 라벨 찾기 참조).
Agent Platform은 자체 헤더의 작은 집합인 x-vertex-ai-llm-request-type 및 x-vertex-ai-llm-shared-request-type도 캡처합니다. 다른 헤더는 캡처되지 않습니다.
헤더 라벨은 Gemini와 Claude에서 동일한 방식으로 작동하며, 추론 요청 메타데이터 로그에서 Claude 요청에 라벨을 지정하는 방법입니다.
헤더 라벨 한도
- 단일 요청은 최대 32개의 헤더를 작성합니다. 적격한 항목이 더 많으면 에이전트 플랫폼은 알파벳 오름차순으로 유지하고 나머지는 삭제합니다. 삭제는 자동으로 이루어집니다.
- 1,024바이트를 초과하는 헤더 값은 잘리고 잘린 부분은 저장된 값에 표시됩니다.
- 이름이 동일한 반복되는 헤더는 여러 값이 있는 단일 항목으로 결합됩니다.
헤더 라벨을 쿼리하려면 커스텀 헤더 라벨별 사용량을 참조하세요.
라벨 요구사항
API 호출에 적용된 라벨은 다음 요구사항을 충족해야 합니다.
- 각 API 호출에는 Google 모델의 경우 최대 64개의 라벨, 파트너 모델의 경우 최대 32개의 라벨을 사용할 수 있습니다.
- 각 라벨은 키-값 쌍이어야 합니다.
- 키는 비워 둘 수 없으며 최소 길이는 1자(영문 기준)이고 최대 길이는 63자(영문 기준)입니다. 값은 비워 둘 수 있으며 최대 길이는 63자(영문 기준)입니다.
- 키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다. 키는 소문자나 국제 문자로 시작해야 합니다.
- 라벨의 키 부분은 단일 API 호출에서 고유해야 합니다. 그러나 여러 호출에 같은 키를 사용할 수 있습니다.
이러한 한도는 각 라벨의 키와 값 및 라벨이 있는 개별 API 호출에 적용됩니다. 한 프로젝트의 모든 API 호출에서 만들 수 있는 라벨 키 수에는 제한이 없습니다. 각 라벨 키는 연결된 결제 계정의 전체 기간 동안 모든 요청에서 최대 1,000개의 고유 값을 가질 수 있습니다. 라벨 키에 1,000개 이상의 고유 값이 연결된 경우 라벨 키가 예고 없이 삭제될 수 있습니다.
라벨의 일반적인 사용 사례
다음은 라벨의 몇 가지 일반적인 사용 사례입니다.
팀 또는 비용 센터 라벨: 팀 또는 비용 센터를 기준으로 라벨을 추가하여 서로 다른 팀(예:
team:research및team:analytics)에서 소유하는 API 호출을 구분할 수 있습니다. 비용 계산이나 예산 책정에 이 유형의 라벨을 사용할 수 있습니다.구성요소 라벨:
component:redis,component:frontend,component:ingest,component:dashboard를 예로 들 수 있습니다.환경 또는 단계 라벨:
environment:production과environment:test를 예로 들 수 있습니다.소유권 라벨: 작업을 담당하는 팀을 식별하는 데 사용됩니다(예:
team:shopping-cart).
모든 API 호출의 타임스탬프 또는 개별 값과 같은 다수의 고유 라벨을 만들지 않는 것이 좋습니다. 고유 키를 많이 만들면 카탈로그가 복잡해지고 쿼리 중에 로드 시간이 크게 늘어나며 API 호출을 효과적으로 필터링하고 보고하기가 어려워집니다.
요청 라벨에 지원되는 모델
요청 라벨과 헤더 라벨은 모델에 따라 지원됩니다. 요청에 요청 라벨을 추가하는 기능은 Google 모델과 일부 파트너 모델에서 지원됩니다. 지원되지 않는 모델의 요청에 요청 라벨을 추가하면 요청에서 오류가 발생합니다. Google 모델은 요청 본문의 labels 필드에서 요청 라벨을 사용합니다. 파트너 모델은 X-Vertex-AI-Labels 헤더에서 이를 가져옵니다.
Google 모델
Google 모델은 다음 API 메서드에서 라벨을 지원합니다.
generateContentstreamGenerateContentinteractions.create
파트너 모델
파트너 모델은 다음 API 메서드에서 라벨을 지원합니다.
rawPredictstreamRawPredict
다음 파트너 모델은 라벨을 지원합니다.
라벨은 요청에서 PayGo 소비 옵션을 사용하는 경우에만 Cloud Billing으로 전달됩니다. 프로비저닝된 처리량 소비 옵션을 사용하는 요청은 요청에 전송된 라벨을 자동으로 무시합니다.
헤더 라벨에 지원되는 모델
헤더 라벨은 추론 요청 메타데이터 로그에만 기록되므로 로그가 기록하는 모델 및 메서드에서 작동합니다.
- Gemini 모델:
generateContent및streamGenerateContent - Claude 모델:
rawPredict및streamRawPredict - 소비 옵션: 프로비저닝된 처리량 및 모델에서 제공하는 모든 사용한 만큼만 지불 옵션
- Mistral AI를 비롯한 다른 파트너 모델은 지원되지 않습니다. 헤더 라벨이 있는 요청은 계속 성공하지만 로그 항목이 작성되지 않으므로 라벨이 어디에도 기록되지 않습니다.
- 헤더 라벨은 Cloud Billing에 도달하지 않습니다. 청구 금액을 분류하려면 요청 라벨을 사용합니다.
Google 모델 API 호출에 요청 라벨 추가
generateContent, streamGenerateContent 또는 interactions.create API 호출에 라벨을 추가하려면 다음 안내를 따르세요.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
GENERATE_RESPONSE_METHOD: 모델에서 생성하려는 응답 유형입니다. 모델의 응답을 반환할 방법을 생성하는 메서드를 선택합니다.streamGenerateContent: 지연 시간에 대한 인식을 줄이기 위해 응답이 생성되는 동안 스트리밍됩니다.generateContent: 응답은 완전히 생성된 후에 반환됩니다.
LOCATION: 요청을 처리하는 리전입니다.PROJECT_ID: 프로젝트 ID입니다. .MODEL_ID: 사용하려는 모델의 모델 ID입니다.ROLE: 콘텐츠와 연결된 대화의 역할입니다. 싱글턴 사용 사례에서도 역할을 지정해야 합니다. 허용되는 값은 다음과 같습니다.USER: 전송한 콘텐츠를 지정합니다.MODEL: 모델의 응답을 지정합니다.
PROMPT_TEXT
LABEL_KEY: 이 API 호출과 연결할 라벨 메타데이터입니다.LABEL_VALUE: 라벨 값입니다.
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json 파일에 저장합니다.
터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.
cat > request.json << 'EOF'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
EOF그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
요청 본문을 request.json 파일에 저장합니다.
터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.
@'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
'@ | Out-File -FilePath request.json -Encoding utf8그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.
$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 수신됩니다.
Python
이 샘플을 사용해 보기 전에 Agent Platform 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요.
Agent Platform에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Google Cloud 제품은 다양한 간격으로 Cloud Billing 프로세스에 사용량 및 비용 데이터를 보고합니다. 따라서Google Cloud 서비스 사용과 Cloud Billing에서 볼 수 있는 사용량 및 비용 사이에 지연이 발생할 수 있습니다. 일반적으로 비용은 1일 이내에 제공되지만 경우에 따라 24시간이 초과될 수도 있습니다.
파트너 모델 API 호출에 요청 라벨 추가
rawPredict 또는 streamRawPredict API 호출에 라벨을 추가하려면 다음 안내를 따르세요.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.MODEL_ID: 사용하려는 모델의 모델 ID입니다. 예를 들면claude-opus-4-6입니다.
요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.
cat > request.json << 'EOF'
{
"anthropic_version": "vertex-2023-10-16",
"messages": [
{
"role": "user",
"content": "What is Generative AI?"
}
],
"max_tokens": 1024,
"stream": false
}
EOF
그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.
REQUEST_LABELS=$(echo -n '{"team": "research", "component": "frontend"}' | base64 --wrap 0)
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Vertex-AI-Labels: ${REQUEST_LABELS}" \
-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_ID:rawPredict"
Python
이 샘플을 사용해 보기 전에 Agent Platform 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요.
Agent Platform에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.MODEL_ID: 사용하려는 모델의 모델 ID입니다. 예를 들면claude-opus-4-6입니다.
import base64 import json from google.cloud.aiplatform import aiplatform_v1 from google.api import httpbody_pb2 project_id = "PROJECT_ID" model_id = "MODEL_ID" request_body = { "anthropic_version": "vertex-2023-10-16", "messages": [{ "role": "user", "content": [{"type": "text", "text": "What is Generative AI?"}] }], "max_tokens": 256, "stream": True, } # Encode labels to base64 for the X-Vertex-AI-Labels header labels = { "team": "research", "component": "frontend", "environment": "production", } labels_json = json.dumps(labels).encode("utf-8") vertex_header_value = base64.b64encode(labels_json) endpoint_id=f"projects/{project_id}/locations/global/publishers/anthropic/models/{model_id}" client = aiplatform_v1.PredictionServiceClient() responses = client.stream_raw_predict( request=aiplatform_v1.StreamRawPredictRequest( endpoint=endpoint_id, http_body=httpbody_pb2.HttpBody( data=json.dumps(request_body).encode("utf-8"), content_type="application/json", ), ), metadata=[("x-vertex-ai-labels", vertex_header_value)], ) for response in responses: print(response.data.decode("utf-8"))
API 호출에 헤더 라벨 추가
헤더 라벨은 요청 본문을 변경할 필요가 없습니다. 지원되는 요청에 라벨당 x-goog-agent-platform-observability-label-KEY 헤더를 하나씩 추가합니다. 다음 예시는 2026년 10월 14일의 테스트 요청에서 추론 요청 메타데이터 로그 항목의 요청과 결과 필드를 보여줍니다.
Gemini 모델 API 호출에 헤더 라벨 추가
generateContent 또는 streamGenerateContent가 있는 헤더 라벨을 전송합니다. PROJECT_ID를 프로젝트 ID로 바꿉니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-agent-platform-observability-label-team: payments" \
-H "x-goog-agent-platform-observability-label-application: invoice-ocr" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \
-d '{"contents": [{"role": "user", "parts": [{"text": "What is Generative AI?"}]}]}'
로그 항목은 jsonPayload.httpHeaders 아래에 각 라벨을 기록합니다. 헤더 라벨은 프로비저닝된 처리량 트래픽에도 기록되며, 요청 라벨은 지원하지 않습니다.
{
"method": "GENERATE_CONTENT",
"trafficType": "PROVISIONED_THROUGHPUT",
"httpHeaders": {
"x-goog-agent-platform-observability-label-application": {"values": ["invoice-ocr"]},
"x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
},
"generateContentDetails": {"usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 1, "totalTokenCount": 7}},
"provisionedThroughput": {"accountingResource": "projects/PROJECT_NUMBER", "ptChargedInputTokenCount": "6", "ptChargedOutputTokenCount": "9"}
}
Claude 모델 API 호출에 헤더 라벨 추가
rawPredict 또는 streamRawPredict가 있는 헤더 라벨을 전송합니다. PROJECT_ID 및 MODEL_ID를 바꿉니다(예: claude-opus-4-6).
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-agent-platform-observability-label-team: payments" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict" \
-d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "What is Generative AI?"}], "max_tokens": 256}'
로그 항목은 Claude의 토큰 수 옆에 있는 jsonPayload.httpHeaders 아래에 라벨을 기록합니다.
{
"method": "RAW_PREDICT",
"trafficType": "ON_DEMAND",
"httpHeaders": {
"x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
},
"rawPredictDetails": {"usageMetadata": {"input_tokens": 17, "output_tokens": 16, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}
}
Claude 요청은 파트너 모델 API 호출에 요청 라벨 추가에 표시된 대로 X-Vertex-AI-Labels 헤더에 요청 라벨을 전달할 수도 있습니다.
이러한 필드는 Cloud Billing에 도달하지만 로그 항목에 기록되지 않습니다.
쿼리 헤더 라벨
로그 탐색기에서 헤더 라벨 값 하나를 필터링합니다.
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
Observability Analytics에서 추론 요청 메타데이터 로깅 페이지의 커스텀 헤더 라벨별 사용량 쿼리를 사용하여 헤더 라벨별로 그룹화합니다.