커스텀 메타데이터 라벨

라벨을 사용하여 generateContent 및 streamGenerateContent API 호출에 커스텀 메타데이터를 추가할 수 있습니다. 이 페이지에서는 라벨의 정의와 라벨을 사용하여 청구 요금을 분류하는 방법을 설명합니다.

라벨이란 무엇인가요?

라벨은 generateContent 및 streamGenerateContent API 호출에 할당할 수 있는 키-값 쌍입니다. 이러한 호출을 구성하고 필요한 세부사항으로 규모에 맞게 비용을 관리하는 데 도움이 됩니다. 각 호출에 라벨을 연결한 다음 해당 라벨을 기준으로 호출을 필터링할 수 있습니다. 라벨에 대한 정보는 청구 요금을 라벨별로 분류할 수 있는 결제 시스템으로 전달됩니다. 기본 제공되는 결제 보고서를 통해 라벨별로 비용을 필터링하고 그룹화할 수 있습니다. 라벨을 사용하여 결제 데이터 내보내기를 쿼리할 수도 있습니다.

라벨 요구사항

API 호출에 적용된 라벨은 다음 요구사항을 충족해야 합니다.

각 API 호출에는 라벨을 최대 64개까지 추가할 수 있습니다.
각 라벨은 키-값 쌍이어야 합니다.
키는 비워 둘 수 없으며 최소 길이는 1자(영문 기준)이고 최대 길이는 63자(영문 기준)입니다. 값은 비워 둘 수 있으며 최대 길이는 63자(영문 기준)입니다.
키와 값에는 소문자, 숫자, 밑줄, 대시만 사용할 수 있습니다. 모든 문자는 UTF-8 인코딩을 사용해야 하며 국제 문자가 허용됩니다. 키는 소문자나 국제 문자로 시작해야 합니다.
라벨의 키 부분은 단일 API 호출에서 고유해야 합니다. 그러나 여러 호출에 같은 키를 사용할 수 있습니다.

이러한 한도는 각 라벨의 키와 값 및 라벨이 있는 개별 API 호출에 적용됩니다. 한 프로젝트의 모든 API 호출에 적용할 수 있는 라벨 수에는 제한이 없습니다.

라벨의 일반적인 사용 사례

다음은 라벨의 몇 가지 일반적인 사용 사례입니다.

팀 또는 비용 센터 라벨: 팀 또는 비용 센터를 기준으로 라벨을 추가하여 서로 다른 팀(예: team:research 및 team:analytics)에서 소유하는 API 호출을 구분할 수 있습니다. 비용 계산이나 예산 책정에 이 유형의 라벨을 사용할 수 있습니다.
구성요소 라벨: component:redis, component:frontend, component:ingest, component:dashboard를 예로 들 수 있습니다.
환경 또는 단계 라벨: environment:production과 environment:test를 예로 들 수 있습니다.
소유권 라벨: 작업을 담당하는 팀을 식별하는 데 사용됩니다(예: team:shopping-cart).

모든 API 호출의 타임스탬프 또는 개별 값과 같은 다수의 고유 라벨을 만들지 않는 것이 좋습니다. 이 접근 방식의 문제는 값이 자주 변경되거나 카탈로그를 복잡하게 하는 키로 인해 API 호출을 효과적으로 필터링하고 보고하기 어렵다는 것입니다.

API 호출에 라벨 추가

generateContent 또는 streamGenerateContent API 호출에 라벨을 추가하려면 다음 안내를 따르세요.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

GENERATE_RESPONSE_METHOD: 모델에서 생성하려는 응답 유형입니다. 모델의 응답을 반환할 방법을 생성하는 메서드를 선택합니다.
- streamGenerateContent: 지연 시간에 대한 인식을 줄이기 위해 응답이 생성되는 동안 스트리밍됩니다.
- generateContent: 응답은 완전히 생성된 후에 반환됩니다.
LOCATION: 요청을 처리하는 리전입니다. 사용 가능한 옵션은 다음과 같습니다.
클릭하여 사용 가능한 리전의 일부 목록 펼치기
- us-central1
- us-west4
- northamerica-northeast1
- us-east4
- us-west1
- asia-northeast3
- asia-southeast1
- asia-northeast1
PROJECT_ID: 프로젝트 ID
MODEL_ID: 사용할 멀티모달 모델의 모델 ID입니다. 몇 가지 옵션을 예로 들면 다음과 같습니다.
- gemini-1.0-pro-002
- gemini-1.0-pro-vision-001
- gemini-1.5-pro-002
- gemini-1.5-flash
ROLE: 콘텐츠와 연결된 대화의 역할입니다. 싱글턴 사용 사례에서도 역할을 지정해야 합니다. 허용되는 값은 다음과 같습니다.
- USER: 전송한 콘텐츠를 지정합니다.
- MODEL: 모델의 응답을 지정합니다.
```
PROMPT_TEXT
```
프롬프트에 포함할 텍스트 요청 사항입니다. JSON
LABEL_KEY: 이 API 호출과 연결할 라벨 메타데이터입니다.
LABEL_VALUE: 라벨의 값입니다.

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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 응답이 수신됩니다.

응답

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

Google Cloud 제품은 다양한 간격으로 Cloud Billing 프로세스에 사용량 및 비용 데이터를 보고합니다. 따라서 Google Cloud 서비스 사용 및 Cloud Billing에서 볼 수 있는 사용량과 비용 사이에 지연이 발생할 수 있습니다. 일반적으로 비용은 1일 이내에 제공되지만 경우에 따라 24시간이 초과될 수도 있습니다.