Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

AI 추론 SMT

AI 추론 단일 메서드 변환 (SMT)을 사용하면 Gemini Enterprise Agent Platform 모델에서 Pub/Sub 메시지에 대한 추론을 얻을 수 있습니다. Agent Platform 엔드포인트에 배포된 자체 맞춤 모델을 사용하거나 Agent Platform을 통해 제공되는 Google 및 파트너 모델을 사용할 수 있습니다. 모델의 추론이 각 메시지에 추가되어 원래 메시지 데이터와 함께 다운스트림 처리에서 사용할 수 있습니다.

AI 추론 SMT의 사용 사례는 다음과 같습니다.

실시간 보강: Pub/Sub를 통해 흐르는 이벤트 데이터에 컨텍스트, 분류, 예측, 감정 또는 삽입을 추가합니다.
간소화된 AI 파이프라인: AI 모델에서 추론을 얻기 위해 중간 서비스가 필요하지 않습니다. Pub/Sub는 AI 모델 호출과 추론을 통한 메시지 보강을 처리합니다.
AI 파이프라인의 지연 시간 감소: 아키텍처에서 추가 네트워크 홉을 삭제하여 엔드 투 엔드 지연 시간을 줄입니다.
흐름 제어 강화: 모델 엔드포인트의 과부하를 방지하기 위해 Pub/Sub은 AI 모델에 대한 요청 비율을 최적화합니다. 자세한 내용은 이 문서의 메시지 흐름을 참고하세요.

AI 추론 SMT는 다음 유형의 모델을 지원합니다.

자체 배포 모델 공유 또는 전용 공개 Agent Platform 엔드포인트에 배포된 오픈, 파트너, 맞춤 모델
서비스형 모델 (MaaS) 모델 배포를 관리할 필요가 없는 Gemini, Claude와 같은 Model Garden을 통해 서비스로 제공되는 모델 AI 추론 SMT와 호환되는 MaaS 모델 목록은 호환되는 MaaS 모델을 참고하세요.

필수 역할 및 권한

SMT로 주제 또는 구독을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Pub/Sub 편집자 (roles/pubsub.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 SMT로 주제 또는 구독을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

SMT로 주제 또는 구독을 만들려면 다음 권한이 필요합니다.

주제 만들기: 프로젝트에 대한 pubsub.topics.create 권한
구독 만들기: 프로젝트에 대한 pubsub.subscriptions.create 권한

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

서비스 계정 권한

AI 추론 SMT는 IAM 서비스 계정을 사용하여 에이전트 플랫폼 엔드포인트를 호출합니다. 기본적으로 Cloud Pub/Sub 서비스 에이전트 계정(service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com)을 사용합니다. 자체 서비스 계정을 제공할 수도 있습니다.

서비스 계정에는 에이전트 플랫폼 엔드포인트가 포함된 Google Cloud프로젝트에 대한 다음 권한이 필요합니다.

aiplatform.endpoints.get
aiplatform.endpoints.predict

이러한 권한을 부여하려면 서비스 계정에 다음 IAM 역할을 부여합니다.

Cloud Pub/Sub 서비스 에이전트 서비스 계정을 사용하는 경우 Vertex AI 서비스 에이전트 역할을 부여합니다.
다른 서비스 계정을 사용하는 경우 Vertex AI 사용자 역할을 부여합니다.

메시지 처리

이 섹션에서는 AI 추론 SMT가 Pub/Sub 메시지를 처리하는 방법을 설명합니다.

입력

Pub/Sub 메시지 데이터는 JSON 문자열로 AI 모델에 전송할 요청이어야 합니다. 각 요청과 함께 전송할 추가 모델 매개변수를 지정할 수도 있습니다. SMT는 이러한 매개변수를 메시지 데이터와 병합하고 병합된 JSON을 모델 엔드포인트로 전송합니다.

다음 표는 모델 유형에 따라 추론을 가져오기 위해 SMT가 호출하는 API를 보여줍니다.

모델 배포	모델 유형	API
자체 배포	전체	`rawPredict`
Model-as-a-Service (MaaS)	Gemini 기반 모델 예: `gemini-3.0-pro`	`Chat Completions API`
	기타 Gemini 모델 예: `gemini-embeddings`	`rawPredict`
	Anthropic, Mistral AI, AI21	`rawPredict`
	기타 모든 MaaS 모델	`Chat Completions API`

메시지 데이터와 모델 파라미터를 올바르게 포맷하려면 모델 문서를 참고하세요. 예를 들어 Gemini 기본 모델의 경우 Chat Completions API 예시를 참고하세요.

출력

모델 엔드포인트 호출이 성공하면 SMT는 모델 응답으로 원래 Pub/Sub 메시지를 보강합니다. 강화된 메시지는 다음과 같은 JSON 문자열입니다. 여기서 ORIGINAL_MESSAGE는 원래 메시지 데이터이고 INFERENCE_RESULT는 모델의 응답입니다.

{
  "original_message": { ORIGINAL_MESSAGE },
  "model_output": { INFERENCE_RESULT }
}

메시지 흐름

주제 SMT: 주제에 AI 추론 SMT를 정의하면 Pub/Sub에서 수신 메시지를 다음과 같이 처리합니다.

게시자 애플리케이션이 Pub/Sub 주제에 메시지를 전송합니다.
메시지가 추론을 위해 구성된 모델 엔드포인트로 전송됩니다. 원본 데이터와 모델의 추론이 포함된 보강된 메시지가 Pub/Sub의 내부 저장소에 기록됩니다.
Pub/Sub는 연결된 모든 구독에 풍부한 메시지를 전달합니다.

구독 SMT: 구독에 AI 추론 SMT를 정의하면 Pub/Sub에서 수신 메시지를 다음과 같이 처리합니다.

게시자 애플리케이션이 Pub/Sub 주제에 메시지를 전송합니다.
Pub/Sub이 구독으로 메시지를 전달합니다.
메시지가 추론을 위해 구성된 모델 엔드포인트로 전송됩니다.
구독이 보강된 메시지를 구독자 애플리케이션으로 전송합니다.
Pub/Sub는 배포의 지연 시간과 할당량을 기반으로 처리량을 최대화하도록 AI 모델에 대한 요청 비율을 최적화합니다. 참고: 단항 가져오기 API를 사용하는 경우 이 기능은 지원되지 않습니다.

AI 추론 SMT를 하나 이상의 JavaScript UDF SMT와 연결할 수 있습니다. 이 패턴을 사용하여 모델의 예상 입력 형식에 맞게 메시지를 사전 처리하거나 구독자에게 전달되기 전에 모델의 출력을 사후 처리합니다.

AI 추론 SMT 만들기

SMT는 Pub/Sub 주제 또는 구독에서 구성할 수 있습니다.

주제 SMT는 Pub/Sub가 메시지를 저장하기 전에 실행되며 결과는 모든 구독자가 사용할 수 있습니다.
구독 SMT는 메시지가 전달되기 전에 실행되며 결과는 해당 구독에만 사용할 수 있습니다.

콘솔

Google Cloud 콘솔에서 Pub/Sub 주제 페이지로 이동합니다.

주제로 이동
주제 또는 구독을 만듭니다.
- 주제를 만들려면 주제 만들기를 클릭합니다. 주제 만들기 페이지가 열립니다.
- 구독을 만들려면 다음 단계를 따르세요.
  1. 구독을 원하는 주제의 이름을 클릭합니다.
  2. 구독 만들기를 클릭합니다. 주제에 구독 추가 페이지가 열립니다.
변환에서 변환 추가를 클릭합니다.
변환 유형으로 AI 추론을 선택합니다.
엔드포인트에 모델 엔드포인트의 전체 리소스 이름을 입력합니다.
- 자체 배포 모델: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
- Model Garden 모델: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME
선택사항입니다. 에이전트 플랫폼 엔드포인트를 호출할 때 사용할 서비스 계정을 선택합니다. 자세한 내용은 서비스 계정 권한을 참고하세요.
선택사항입니다. 매개변수 필드에 모델 매개변수를 JSON 객체로 입력합니다. SMT는 모델을 호출하기 전에 이러한 파라미터를 각 메시지와 병합합니다. 예:
```
{
  "temperature": 0.5,
  "max_tokens": 1000
}
```
주제 또는 구독을 만들려면 만들기를 클릭합니다.

gcloud

정의 파일 만들기

추론 AI를 정의하는 YAML 또는 JSON 파일을 만듭니다.

YAML

- aiInference:
    endpoint: "ENDPOINT_RESOURCE"
    unstructuredInference: {
        parameters:
          MODEL_PARAMETERS
    }
    service_account_email: SERVICE_ACCOUNT

JSON

{
  "aiInference": {
    "endpoint": "ENDPOINT_RESOURCE",
    "unstructuredInference": {
        "parameters": {
          MODEL_PARAMETERS
        }
    }
    "service_account_email": SERVICE_ACCOUNT
  }
}

다음을 바꿉니다.

ENDPOINT_RESOURCE: 모델 엔드포인트의 전체 리소스 이름입니다. 다음 형식을 사용합니다.
- 자체 배포 모델: projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT
- Model Garden 모델: projects/PROJECT/locations/LOCATION/publishers/PUBLISHER/models/MODEL_NAME
MODEL_PARAMETERS: 선택사항. 모델 매개변수(JSON 객체로 지정됨) SMT는 모델을 호출하기 전에 이러한 파라미터를 각 메시지와 병합합니다. 예:
```
{
  "temperature": 0.5,
  "max_tokens": 1000
}
```
SERVICE_ACCOUNT: 선택사항. 엔드포인트를 호출할 때 사용할 서비스 계정 이메일입니다. 자세한 내용은 서비스 계정 권한을 참고하세요.

주제 또는 구독 만들기

주제를 만들려면 gcloud pubsub topics create 명령어를 실행합니다.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

다음을 바꿉니다.

TOPIC_ID: 만들려는 주제의 ID 또는 이름입니다.
TRANSFORMS_FILE: 정의 파일의 경로입니다.

구독을 만들려면 gcloud pubsub subscriptions create 명령어를 실행합니다.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

다음을 바꿉니다.

SUBSCRIPTION_ID: 생성할 구독의 ID 또는 이름입니다.
PROJECT_ID: 주제가 포함된 프로젝트의 ID입니다.
TOPIC_ID: 구독할 주제의 ID입니다.
TRANSFORMS_FILE: 정의 파일의 경로입니다.

유효성 검사 및 테스트

선택적으로 주제 또는 구독을 만들기 전에 구성된 SMT를 검증하고 테스트할 수 있습니다. 자세한 내용은 다음 문서를 참조하세요.

예: AI 추론 SMT 사용

다음 예에서는 AI 추론 SMT로 구독을 만든 다음 이를 사용하여 Gemini에 프롬프트를 전송하는 방법을 보여줍니다.

gcloud

텍스트 편집기를 사용하여 ai-smt.yaml 파일을 만들고 다음 텍스트를 붙여넣습니다.

- aiInference:
    endpoint: projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash
    unstructuredInference: {
        parameters: {
            "max_tokens": 25000
        }
    }

다음을 바꿉니다.

PROJECT_ID: Google Cloud프로젝트의 ID입니다.
LOCATION: 호출할 엔드포인트의 위치입니다. 예: us-central1

새 Pub/Sub 주제를 만듭니다.
```
gcloud pubsub topics create TOPIC_ID
```
TOPIC_ID을 만들 주제의 이름으로 바꿉니다. 예: topic-1

AI 추론 SMT가 있는 구독을 만듭니다.

gcloud pubsub subscriptions create TOPIC_ID-sub \
  --ack-deadline=600 \
  --topic TOPIC_ID \
  --message-transforms-file ai-smt.yaml

주제에 메시지를 게시합니다. 메시지에는 Chat Completions API용으로 형식이 지정된 프롬프트가 포함되어 있습니다.

gcloud pubsub topics publish TOPIC_ID --message=$'{
  "model":"google/gemini-2.5-flash","messages":[{
    "role": "user",
    "content": "Explain how AI works in a few words"
    }]
  }'

구독에서 메시지를 수신합니다.
```
gcloud pubsub subscriptions pull TOPIC_ID-sub
```
Agent Platform 호출이 성공하면 메시지가 프롬프트의 출력으로 보강됩니다.

호환되는 MaaS 모델

다음 표에는 Google에서 AI 추론 SMT로 테스트했으며 호환되는 것으로 알려진 Model-as-a-Service (MaaS) 모델이 나와 있습니다. 모델이 지원 중단되거나 새 MaaS 모델이 추가되면 이 목록은 변경될 수 있습니다.

모델	API 호출됨
`google/gemini-2.0-flash-001`	Chat Completions API
`google/gemini-2.0-flash-lite-001`	Chat Completions API
`google/gemini-2.5-flash`	Chat Completions API
`google/gemini-2.5-flash-lite`	Chat Completions API
`google/gemini-2.5-pro`	Chat Completions API
`google/gemini-2.5-flash-image`	Chat Completions API
`google/gemini-3-pro-preview`	Chat Completions API
`google/gemini-3-pro-image-preview`	Chat Completions API
`google/gemini-3-flash-preview`	Chat Completions API
`google/gemini-3.1-pro-preview`	Chat Completions API
`google/gemini-3.1-flash-image-preview`	Chat Completions API
`google/gemini-3.1-flash-lite-preview`	Chat Completions API
`meta/llama-3.3-70b-instruct-maas`	Chat Completions API
`meta/llama-4-maverick-17b-128e-instruct-maas`	Chat Completions API
`meta/llama-4-scout-17b-16e-instruct-maas`	Chat Completions API
`deepseek-ai/deepseek-r1-0528-maas`	Chat Completions API
`deepseek-ai/deepseek-v3.1-maas`	Chat Completions API
`qwen/qwen3-235b-a22b-instruct-2507-maas`	Chat Completions API
`qwen/qwen3-coder-480b-a35b-instruct-maas`	Chat Completions API
`openai/gpt-oss-20b-maas`	Chat Completions API
`openai/gpt-oss-120b-maas`	Chat Completions API
`google/text-multilingual-embedding-002`	`rawPredict`
`google/text-embedding-005`	`rawPredict`
`google/text-embedding-large-exp-03-07`	`rawPredict`
`google/gemini-embedding-001`	`rawPredict`
`google/multimodalembedding`	`rawPredict`
`anthropic/claude-sonnet-4`	`rawPredict`
`anthropic/claude-sonnet-4-5`	`rawPredict`
`anthropic/claude-sonnet-4-6`	`rawPredict`
`anthropic/claude-opus-4`	`rawPredict`
`anthropic/claude-opus-4-1`	`rawPredict`
`anthropic/claude-opus-4-5`	`rawPredict`
`anthropic/claude-opus-4-6`	`rawPredict`
`anthropic/claude-haiku-4-5`	`rawPredict`
`mistralai/mistral-small-2503`	`rawPredict`
`mistralai/mistral-medium-3`	`rawPredict`
`mistralai/mistral-ocr-2505`	`rawPredict`
`mistralai/codestral-2`	`rawPredict`

제한사항

주제 또는 구독당 하나의 AI 추론 SMT만 허용됩니다.
비공개 엔드포인트는 지원되지 않습니다. 자체 배포 모델은 공개 Agent Platform 엔드포인트에서 호스팅해야 합니다.
전역 엔드포인트는 Gemini 파운데이션 모델에서만 지원됩니다. 다른 모델의 경우 리전 엔드포인트를 사용해야 합니다.
Pub/Sub는 입력 메시지 데이터를 검증하지 않습니다. 데이터 형식이 올바른지 확인하는 책임은 개발자에게 있습니다.
변환은 Pub/Sub 메시지당 하나의 추론 요청을 전송합니다. 클라이언트 측 일괄 처리가 실행되지 않습니다.
비동기 일괄 추론은 지원되지 않습니다.
추론은 60초를 초과해서는 안 됩니다. 60초를 초과하면 전송 시도가 시간 초과되고 Pub/Sub가 구성된 메시지 보관 기간 및 재시도 정책 설정까지 재시도합니다. 시도가 시간 초과되면 메시지가 데드 레터 주제로 전달됩니다(구성된 경우).

지원되지 않는 모델

AI 추론 SMT는 다음 MaaS 모델을 지원하지 않습니다. 이러한 모델 중 상당수는 대신 사용할 수 있는 자체 배포 버전이 제공됩니다.

deepseek-ai/deepseek-ocr-maas
deepseek-ai/deepseek-v3.2-maas
google/gemini-embedding-2-preview
google/lyria-002
google/lyria-3-clip-preview
google/lyria-3-pro-preview
google/veo-3.1-fast-generate-001
google/veo-3.1-generate-001
intfloat/multilingual-e5-large-instruct-maas
intfloat/multilingual-e5-small-instruct-maas
minimaxai/minimax-m2-maas
moonshotai/kimi-k2-thinking-maas
qwen/qwen3-next-80b-a3b-instruct-maas
qwen/qwen3-next-80b-a3b-thinking-maas
zai-org/glm-4.7-maas
zai-org/glm-5-maas

지역 제약 조건

다음 제약 조건은 에이전트 플랫폼 엔드포인트의 리전에 따라 AI 추론 SMT에 적용됩니다.

주제에 AI 추론 SMT가 정의된 경우 엔드포인트 리전은 주제의 메시지 스토리지 정책에서 허용하는 리전 내에 있어야 합니다.

이 제약 조건은 Pub/Sub 메시지에 전송 중인 리전 적용 조직 정책 제약 조건이 적용되는 경우 구독 SMT에도 적용됩니다.
내보내기 구독에 AI 추론 SMT가 정의된 경우 엔드포인트 리전은 연결된 리소스의 리전이어야 합니다.
- BigQuery 구독의 경우 대상 테이블의 리전입니다.
- Cloud Storage 구독의 경우 Cloud Storage 버킷의 리전입니다.
엔드포인트 리전이 아닌 다른 리전에 게시 요청이 이루어지면 Pub/Sub가 자동으로 요청을 엔드포인트 리전으로 리디렉션합니다.
AI 추론 SMT가 있는 구독에서 가져오고 pull 요청이 엔드포인트 리전이 아닌 다른 리전으로 전송되면 Pub/Sub에서 요청을 거부합니다. 풀 구독에는 위치 엔드포인트를 사용하는 것이 좋습니다. 이 제약 조건은 스트리밍 풀과 단항 풀 모두에 적용됩니다.
푸시 구독에 AI 추론 SMT가 있는 경우 구독은 엔드포인트 리전에서 메시지를 푸시합니다. 리전 제약조건 위반이 발생하면 Pub/Sub가 해당 구독에서 메시지 푸시를 중지합니다.

문제 해결

이 섹션에서는 AI 추론 SMT의 문제 해결 팁을 제공합니다.

주제 SMT 오류 메시지가 게시될 때 추론이 실패하면 전체 게시 요청이 실패합니다. 오류 정보가 게시자 클라이언트에 반환됩니다.
구독 SMT 오류 메시지가 전송될 때 추론이 실패하면 메시지를 데드 레터 주제로 전달할 수 있습니다. 구독에서 SMT를 사용하는 경우 데드 레터 주제를 설정하는 것이 좋습니다.
모델 추론 오류 추론이 실패하고 오류가 반환되면 다음을 확인하세요.
- 구성된 엔드포인트가 올바른지 확인합니다.
- Pub/Sub 메시지 데이터에 모델의 유효한 추론 요청이 포함되어 있는지 확인합니다.
- 모든 모델 매개변수가 유효한지 확인합니다.
연결 문제와 같은 다른 이유로 추론이 실패할 수 있습니다.
권한 또는 엔드포인트 오류 구성된 서비스 계정에 엔드포인트에 대한 권한이 없거나 엔드포인트가 삭제되면 SMT가 실패합니다.

할당량 및 한도

Pub/Sub 할당량 및 한도 외에도 AI 추론 SMT에는 에이전트 플랫폼 엔드포인트의 할당량 및 비율 제한이 적용됩니다. Pub/Sub의 기본 제공 흐름 제어 기능은 엔드포인트의 과부하를 방지하기 위해 요청 비율을 자동으로 조정하지만 비율은 모델의 할당량을 초과할 수 없습니다.
원래 메시지와 추론 출력을 포함한 최종 변환된 메시지 크기는 Pub/Sub 메시지 크기 한도보다 작아야 합니다. 변환된 메시지가 한도를 초과하면 변환이 실패합니다.

AI 추론 SMT 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

필수 역할 및 권한

필수 권한

서비스 계정 권한

메시지 처리

입력

출력

메시지 흐름

AI 추론 SMT 만들기

콘솔

gcloud

정의 파일 만들기

YAML

JSON

주제 또는 구독 만들기

유효성 검사 및 테스트

예: AI 추론 SMT 사용

gcloud

호환되는 MaaS 모델

제한사항

지원되지 않는 모델

지역 제약 조건

문제 해결

할당량 및 한도

다음 단계

AI 추론 SMT