Google Vertex 프로바이더

Google Vertex 프로바이더 사용법 (Google Vertex Provider Usage)

Google Vertex 프로바이더 인스턴스는 Vertex AI API를 호출하는 모델 인스턴스를 만드는 데 사용돼요. 이 프로바이더에서 사용할 수 있는 모델에는 Google의 Gemini 모델이 있어요. Anthropic의 Claude 모델을 사용하려면 아래의 Google Vertex Anthropic 프로바이더 섹션을 참고하세요.

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/google-vertex에서 기본 프로바이더 인스턴스 googleVertex를 불러올 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex';

커스터마이즈가 필요하다면 @ai-sdk/google-vertex에서 createGoogleVertex를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createGoogleVertex } from '@ai-sdk/google-vertex';

const googleVertex = createGoogleVertex({
  project: 'my-project', // optional
  location: 'us-central1', // optional
});

Google Vertex는 런타임 환경과 요구 사항에 따라 여러 인증 방법을 지원해요.

Node.js 런타임

Node.js 런타임은 AI SDK가 지원하는 기본 런타임이에요. google-auth-library를 통해 모든 표준 Google Cloud 인증 옵션을 지원해요. 일반적으로 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 json 자격 증명 파일 경로를 설정해 사용해요. 자격 증명 파일은 Google Cloud Console에서 얻을 수 있어요.

Google 인증 옵션을 커스터마이즈하려면 createGoogleVertex 함수의 옵션으로 전달할 수 있어요. 예를 들면:

import { createGoogleVertex } from '@ai-sdk/google-vertex';

const googleVertex = createGoogleVertex({
  googleAuthOptions: {
    credentials: {
      client_email: 'my-email',
      private_key: 'my-private-key',
    },
  },
});

선택적 프로바이더 설정 (Optional Provider Settings)

프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• project string

  API 호출에 사용할 Google Cloud 프로젝트 ID예요. 기본적으로 GOOGLE_VERTEX_PROJECT 환경 변수를 사용해요.

• location string

  API 호출에 사용할 Google Cloud 위치예요. 예: us-central1. 기본적으로 GOOGLE_VERTEX_LOCATION 환경 변수를 사용해요.

• googleAuthOptions object

  선택 사항이에요. Google Auth Library가 사용하는 인증 옵션이에요. GoogleAuthOptions 인터페이스도 참고하세요.

  • authClient object 사용할 AuthClient예요.

  • keyFilename string .json, .pem 또는 .p12 키 파일 경로예요.

  • keyFile string .json, .pem 또는 .p12 키 파일 경로예요.

  • credentials object client_email과 private_key 속성, 또는 외부 계정 클라이언트 옵션을 담은 객체예요.

  • clientOptions object 클라이언트의 생성자에 전달되는 옵션 객체예요.

  • scopes string | string[] 원하는 API 요청에 필요한 스코프예요.

  • projectId string 프로젝트 ID예요.

  • universeDomain string 주어진 Cloud universe의 기본 서비스 도메인이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요. 여러 형식으로 제공할 수 있어요:

  • 헤더 키-값 쌍 레코드: Record<string, string | undefined>
  • 헤더를 반환하는 함수: () => Record<string, string | undefined>
  • 헤더를 반환하는 async 함수: async () => Record<string, string | undefined>
  • 헤더로 해석되는 프로미스: Promise<Record<string, string | undefined>>

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

• baseURL string

  선택 사항이에요. Google Vertex API 호출의 기본 URL이에요. 예를 들어 프록시 서버를 쓸 때 유용해요. 기본적으로 location과 project로 구성돼요: https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google

• toolResultDownloads object

  툴 결과의 원격 파일을 Vertex에 인라인 데이터로 보내기 전에 다운로드하는 설정이에요. 지원되는 Google Cloud Storage URL은 Gemini 3 이상 모델에서 직접 전달돼요. 지원되는 MIME 타입은 Tool Result Files를 참고하세요.

  • maxBytes number

    각 다운로드 파일의 최대 크기(바이트)예요. 기본값은 7 MiB예요.

Edge 런타임

Edge 런타임(예: Cloudflare Workers)은 네트워크 엣지에서 사용자에 더 가깝게 실행되는 가벼운 JavaScript 환경이에요. 표준 Node.js API의 일부만 제공해요. 예를 들어 직접적인 파일 시스템 접근은 불가능하고, (표준 Google Auth 라이브러리를 포함한) 많은 Node.js 전용 라이브러리는 호환되지 않아요.

Google Vertex 프로바이더의 Edge 런타임 버전은 환경 변수를 통한 Google의 Application Default Credentials를 지원해요. 값은 Google Cloud Console의 json 자격 증명 파일에서 얻을 수 있어요.

@ai-sdk/google-vertex/edge에서 기본 프로바이더 인스턴스 googleVertex를 불러올 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex/edge';

커스터마이즈가 필요하다면 @ai-sdk/google-vertex/edge에서 createGoogleVertex를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createGoogleVertex } from '@ai-sdk/google-vertex/edge';

const googleVertex = createGoogleVertex({
  project: 'my-project', // optional
  location: 'us-central1', // optional
});

Edge 런타임 인증을 위해서는 Google Default Application Credentials JSON 파일에서 다음 환경 변수를 설정해야 해요:

• GOOGLE_CLIENT_EMAIL
• GOOGLE_PRIVATE_KEY
• GOOGLE_PRIVATE_KEY_ID (선택)

이 값들은 Google Cloud Console의 서비스 계정 JSON 파일에서 얻을 수 있어요.

선택적 프로바이더 설정 (Optional Provider Settings)

프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• project string

  API 호출에 사용할 Google Cloud 프로젝트 ID예요. 기본적으로 GOOGLE_VERTEX_PROJECT 환경 변수를 사용해요.

• location string

  API 호출에 사용할 Google Cloud 위치예요. 예: us-central1. 기본적으로 GOOGLE_VERTEX_LOCATION 환경 변수를 사용해요.

• googleCredentials object

  선택 사항이에요. Edge 프로바이더가 인증에 사용하는 자격 증명이에요. 일반적으로 환경 변수로 설정되며 서비스 계정 JSON 파일에서 파생돼요.

  • clientEmail string 서비스 계정 JSON 파일의 클라이언트 이메일이에요. 기본값은 GOOGLE_CLIENT_EMAIL 환경 변수의 내용이에요.

  • privateKey string 서비스 계정 JSON 파일의 개인 키예요. 기본값은 GOOGLE_PRIVATE_KEY 환경 변수의 내용이에요.

  • privateKeyId string 서비스 계정 JSON 파일의 개인 키 ID예요(선택). 기본값은 GOOGLE_PRIVATE_KEY_ID 환경 변수의 내용이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요. 여러 형식으로 제공할 수 있어요:

  • 헤더 키-값 쌍 레코드: Record<string, string | undefined>
  • 헤더를 반환하는 함수: () => Record<string, string | undefined>
  • 헤더를 반환하는 async 함수: async () => Record<string, string | undefined>
  • 헤더로 해석되는 프로미스: Promise<Record<string, string | undefined>>

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

Express 모드 (Express Mode)

Express 모드는 OAuth나 서비스 계정 자격 증명 대신 API 키를 사용하는 간소화된 인증 방법을 제공해요. express 모드를 사용할 때는 project와 location 설정이 필요하지 않아요.

import { createGoogleVertex } from '@ai-sdk/google-vertex';

const googleVertex = createGoogleVertex({
  apiKey: process.env.GOOGLE_VERTEX_API_KEY,
});

선택적 프로바이더 설정 (Optional Provider Settings)

• apiKey string

  Google Vertex AI의 API 키예요. 제공하면 프로바이더가 OAuth 대신 API 키 인증을 사용하는 express 모드를 사용해요. 기본적으로 GOOGLE_VERTEX_API_KEY 환경 변수를 사용해요.

언어 모델 (Language Models)

프로바이더 인스턴스로 Vertex API를 호출하는 모델을 만들 수 있어요. 첫 번째 인자는 모델 id예요. 예: gemini-3.8-flash.

const model = googleVertex('gemini-3.8-flash');

Google Vertex 모델은 표준 호출 설정에 속하지 않는 모델별 설정도 지원해요. 그것들을 옵션 인자로 전달할 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';

const model = googleVertex('gemini-3.1-pro-preview');

await generateText({
  model,
  providerOptions: {
    vertex: {
      safetySettings: [
        {
          category: 'HARM_CATEGORY_UNSPECIFIED',
          threshold: 'BLOCK_LOW_AND_ABOVE',
        },
      ],
    } satisfies GoogleLanguageModelOptions,
  },
});

Google Vertex 모델에 사용할 수 있는 선택적 프로바이더 옵션은 다음과 같아요:

• cachedContent string

  선택 사항이에요. 예측을 제공할 때 컨텍스트로 사용되는 캐시된 콘텐츠의 이름이에요. 형식: projects/{project}/locations/{location}/cachedContents/{cachedContent}

• structuredOutputs boolean

  선택 사항이에요. 구조화된 출력을 활성화해요. 기본값은 true예요.

  JSON Schema에 Google Vertex가 사용하는 OpenAPI 스키마 버전에서 지원하지 않는 요소가 포함된 경우 유용해요. 필요하다면 이를 사용해 구조화된 출력을 비활성화할 수 있어요.

  자세한 내용은 트러블슈팅: 스키마 제한을 참고하세요.

• safetySettings Array<{ category: string; threshold: string }>

  선택 사항이에요. 모델의 안전 설정이에요.

  • category string

    안전 설정의 카테고리예요. 다음 중 하나일 수 있어요:

    • HARM_CATEGORY_UNSPECIFIED
    • HARM_CATEGORY_HATE_SPEECH
    • HARM_CATEGORY_DANGEROUS_CONTENT
    • HARM_CATEGORY_HARASSMENT
    • HARM_CATEGORY_SEXUALLY_EXPLICIT
    • HARM_CATEGORY_CIVIC_INTEGRITY

  • threshold string

    안전 설정의 임계값이에요. 다음 중 하나일 수 있어요:

    • HARM_BLOCK_THRESHOLD_UNSPECIFIED
    • BLOCK_LOW_AND_ABOVE
    • BLOCK_MEDIUM_AND_ABOVE
    • BLOCK_ONLY_HIGH
    • BLOCK_NONE

• audioTimestamp boolean

  선택 사항이에요. 오디오 파일의 타임스탬프 이해를 활성화해요. 기본값은 false예요.

  정확한 타임스탬프가 있는 트랜스크립트를 생성하는 데 유용해요. 사용법에 대한 자세한 내용은 Google 문서를 참고하세요.

• labels object

  선택 사항이에요. 결제 보고서에 사용되는 레이블을 정의해요.

  사용법에 대한 자세한 내용은 Google 문서를 참고하세요.

• imageConfig object

  선택 사항이에요. 이미지 생성을 위한 구성이에요. Gemini 이미지 모델에서만 지원돼요.

  사용법에 대한 자세한 내용은 Google의 GenerationConfig 문서를 참고하세요.

  • aspectRatio string

    선택 사항이에요. 생성된 이미지의 종횡비예요. 기본값은 1:1 정사각형이거나 출력 이미지 크기를 입력 이미지와 일치시키는 거예요. 다음 중 하나일 수 있어요:

    • 1:1
    • 2:3
    • 3:2
    • 3:4
    • 4:3
    • 4:5
    • 5:4
    • 9:16
    • 16:9
    • 21:9

  • imageSize string

    선택 사항이에요. 출력 이미지 해상도를 조절해요. 기본값은 1K예요. 다음 중 하나일 수 있어요:

    • 1K
    • 2K
    • 4K

  • personGeneration string

    선택 사항이에요. 이미지에서 사람 생성 여부를 조절해요. 다음 중 하나일 수 있어요:

    • PERSON_GENERATION_UNSPECIFIED
    • ALLOW_ALL
    • ALLOW_ADULT
    • ALLOW_NONE

  • prominentPeople string

    선택 사항이에요. 유명인(저명 인물) 생성 허용 여부를 조절해요. personGeneration과 함께 설정하면 personGeneration이 우선해요. 다음 중 하나일 수 있어요:

    • PROMINENT_PEOPLE_UNSPECIFIED
    • ALLOW_PROMINENT_PEOPLE
    • BLOCK_PROMINENT_PEOPLE

  • imageOutputOptions { mimeType?: 'image/jpeg' | 'image/png', compressionQuality?: number }

    선택 사항이에요. 생성된 이미지의 이미지 출력 형식이에요.

• streamFunctionCallArguments boolean

  선택 사항이에요. true로 설정하면 스트리밍 응답에서 함수 호출 인자가 점진적으로 스트리밍돼요. 이렇게 하면 모델이 함수 호출 인자를 생성할 때 tool-input-delta 이벤트가 도착해서 툴 호출의 인지된 지연 시간을 줄여줘요. 기본값은 false예요. Gemini 3+ 모델에서만 Vertex AI API(아님 Gemini API)에서 지원돼요.

  자세한 내용은 Google 문서를 참고하세요.

• sharedRequestType 'priority' | 'flex' | 'standard'

  선택 사항이에요. X-Vertex-AI-LLM-Shared-Request-Type 요청 헤더를 설정해 종량제(PayGo) 티어를 선택해요. 'priority'는 프리미엄 요금으로 일관된 저지연 성능을, 'flex'는 더 긴 예상 지연 시간과 함께 50% 할인을 제공해요. 둘 다 global 엔드포인트와 일부 Gemini 모델에서만 지원돼요.

  기본적으로 — Provisioned Throughput이 할당되어 있고 requestType이 설정되지 않은 경우 — 요청은 먼저 Provisioned Throughput 할당량을 사용하고, PT 용량이 소진된 경우에만 선택한 공유 티어로 대체돼요. Provisioned Throughput을 완전히 건너뛰려면 requestType: 'shared'도 설정하세요.

  제공된 티어는 result.providerMetadata.googleVertex.usageMetadata.trafficType에 ON_DEMAND_PRIORITY, ON_DEMAND_FLEX 또는 (부하 시 다운그레이드되면) 일반 ON_DEMAND로 보고돼요.

  지원 모델, 램프 한도, 다운그레이드 동작은 Priority PayGo와 Flex PayGo를 참고하세요.

• requestType 'shared'

  선택 사항이에요. X-Vertex-AI-LLM-Request-Type 요청 헤더를 설정해요. sharedRequestType와 함께 사용하면 Provisioned Throughput을 완전히 건너뛰고 공유 PayGo 용량으로 요청을 라우팅해요. Priority PayGo를 참고하세요.

generateText 함수로 Google Vertex 언어 모델을 사용해 텍스트를 생성할 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const { text } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Google Vertex 언어 모델은 streamText 함수에서도 사용할 수 있어요 (AI SDK Core 참고).

튜닝된 모델 (Tuned Models)

튜닝된 모델은 배포된 엔드포인트에서 서빙되며, 게시된 모델 이름이 아니라 엔드포인트 id로 주소가 지정돼요. endpoints/ 접두사가 있는 엔드포인트 리소스를 전달하면 프로바이더가 기본 모델 경로(.../publishers/google/models/{MODEL_ID}) 대신 배포된 엔드포인트(.../locations/{location}/endpoints/{ENDPOINT_ID})로 요청을 라우팅해요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const { text } = await generateText({
  model: googleVertex('endpoints/YOUR_ENDPOINT_ID'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

배포된 엔드포인트 id를 사용하세요. 튜닝된 모델 id가 아니라요(튜닝된 모델은 models/... 리소스와 별도의 endpoints/... 리소스를 모두 가지며, 추론에는 엔드포인트만 호출 가능해요). 요청과 응답 형식은 기본 모델과 동일하므로 모든 표준 호출 설정과 프로바이더 옵션이 계속 동작해요.

코드 실행 (Code Execution)

코드 실행을 통해 Vertex AI의 특정 Gemini 모델은 Python 코드를 생성하고 실행할 수 있어요. 이를 통해 모델이 계산, 데이터 조작 및 기타 프로그래밍 작업을 수행해 응답을 향상시킬 수 있어요.

요청에 code_execution 툴을 추가해 코드 실행을 활성화할 수 있어요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  tools: { code_execution: googleVertex.tools.codeExecution({}) },
  prompt:
    'Use python to calculate 20th fibonacci number. Then find the nearest palindrome to it.',
});

응답에는 실행된 코드에 대한 tool-call 및 tool-result 파트가 포함돼요.

URL 컨텍스트 (URL Context)

URL Context를 사용하면 Gemini 모델이 URL에서 콘텐츠를 검색하고 분석할 수 있어요. 지원 모델: Gemini 2.5 Flash-Lite, 2.5 Pro, 2.5 Flash, 2.0 Flash.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  tools: { url_context: googleVertex.tools.urlContext({}) },
  prompt: 'What are the key points from https://example.com/article?',
});

Google 검색 (Google Search)

Google Search를 사용하면 Gemini 모델이 실시간 웹 정보에 접근할 수 있어요. 지원 모델: Gemini 2.5 Flash-Lite, 2.5 Flash, 2.0 Flash, 2.5 Pro.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  tools: { google_search: googleVertex.tools.googleSearch({}) },
  prompt: 'What are the latest developments in AI?',
});

Enterprise 웹 검색 (Enterprise Web Search)

Enterprise Web Search는 금융, 의료, 공공 부문 같은 규제가 엄격한 산업을 위해 설계된 컴플라이언스 중심 웹 인덱스를 사용한 접지(grounding)를 제공해요. 표준 Google Search 접지와 달리 Enterprise Web Search는 고객 데이터를 기록하지 않으며 VPC 서비스 제어를 지원해요. 지원 모델: Gemini 2.0 이상.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.8-flash'),
  tools: {
    enterprise_web_search: googleVertex.tools.enterpriseWebSearch({}),
  },
  prompt: 'What are the latest FDA regulations for clinical trials?',
});

Google Maps

Google Maps 접지를 사용하면 Gemini 모델이 위치 인식 응답을 위해 Google Maps 데이터에 접근할 수 있어요. 지원 모델: Gemini 2.5 Flash-Lite, 2.5 Flash, 2.0 Flash, 2.5 Pro, 3.0 Pro.

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.8-flash'),
  tools: {
    google_maps: googleVertex.tools.googleMaps({}),
  },
  providerOptions: {
    vertex: {
      retrievalConfig: {
        latLng: { latitude: 34.090199, longitude: -117.881081 },
      },
    } satisfies GoogleLanguageModelOptions,
  },
  prompt: 'What are the best Italian restaurants nearby?',
});

선택적인 retrievalConfig.latLng 프로바이더 옵션은 주변 장소에 대한 쿼리의 위치 컨텍스트를 제공해요. 이 구성은 위치 컨텍스트를 지원하는 모든 접지 툴에 적용돼요.

스트리밍 함수 호출 인자 (Streaming Function Call Arguments)

Vertex AI의 Gemini 3 Pro 이상 모델의 경우 streamFunctionCallArguments를 true로 설정하면 함수 호출 인자가 생성되는 대로 스트리밍할 수 있어요. 함수를 호출해야 할 때 tool-input-delta 이벤트가 완전한 인자를 기다리는 대신 점진적으로 도착하므로 인지된 지연 시간이 줄어들어요. 이 옵션의 기본값은 false예요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { streamText } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: 'What is the weather in Boston and San Francisco?',
  tools: {
    getWeather: {
      description: 'Get the current weather in a given location',
      inputSchema: z.object({
        location: z.string().describe('City name'),
      }),
    },
  },
  providerOptions: {
    vertex: {
      streamFunctionCallArguments: true,
    } satisfies GoogleLanguageModelOptions,
  },
});

for await (const part of result.stream) {
  switch (part.type) {
    case 'tool-input-start':
      console.log(`Tool call started: ${part.toolName}`);
      break;
    case 'tool-input-delta':
      process.stdout.write(part.delta);
      break;
    case 'tool-call':
      console.log(`Tool call complete: ${part.toolName}`, part.input);
      break;
  }
}

추론 (Thinking Tokens)

Google Vertex AI는 Gemini 모델 지원을 통해 모델의 추론 과정을 나타내는 "thinking" 토큰도 생성할 수 있어요. AI SDK는 이를 reasoning 정보로 노출해요.

Vertex를 통해 호환 Gemini 모델에서 thinking 토큰을 활성화하려면 thinkingConfig 프로바이더 옵션에서 includeThoughts: true를 설정하세요. 이 옵션들은 providerOptions.vertex를 통해 전달돼요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText, streamText } from 'ai';

// For generateText:
const { text, reasoningText, reasoning } = await generateText({
  model: googleVertex('gemini-3.8-flash'), // Or other supported model via Vertex
  providerOptions: {
    vertex: {
      thinkingConfig: {
        includeThoughts: true,
        // thinkingLevel: 'high', // Optional
      },
    } satisfies GoogleLanguageModelOptions,
  },
  prompt: 'Explain quantum computing in simple terms.',
});

console.log('Reasoning:', reasoningText);
console.log('Reasoning Details:', reasoning);
console.log('Final Text:', text);

// For streamText:
const result = streamText({
  model: googleVertex('gemini-3.8-flash'), // Or other supported model via Vertex
  providerOptions: {
    vertex: {
      thinkingConfig: {
        includeThoughts: true,
        // thinkingLevel: 'high', // Optional
      },
    } satisfies GoogleLanguageModelOptions,
  },
  prompt: 'Explain quantum computing in simple terms.',
});

for await (const part of result.stream) {
  if (part.type === 'reasoning') {
    process.stdout.write(`THOUGHT: ${part.textDelta}\n`);
  } else if (part.type === 'text-delta') {
    process.stdout.write(part.textDelta);
  }
}

includeThoughts가 true이면 thought: true로 표시된 API 응답 파트가 reasoning으로 처리돼요.

• generateText에서는 reasoningText(string) 및 reasoning(array) 필드에 포함돼요.
• streamText에서는 reasoning 스트림 파트로 방출돼요.

파일 입력 (File Inputs)

Google Vertex 프로바이더는 파일 입력(예: PDF 파일)을 지원해요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

const { text } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model according to this document?',
        },
        {
          type: 'file',
          data: fs.readFileSync('./data/ai.pdf'),
          mediaType: 'application/pdf',
        },
      ],
    },
  ],
});

프롬프트에서 파일을 사용하는 방법에 대한 자세한 내용은 File Parts를 참고하세요.

툴 결과 파일 (Tool Result Files)

Gemini 3 이상 모델의 경우 툴 결과에 Google Cloud Storage(gs://) 파일 URL이 포함될 수 있어요. Vertex는 파일을 SDK 프로세스에 다운로드하지 않고 이러한 참조를 functionResponse.parts[].fileData로 직접 받아요. 지원되는 MIME 타입은 image/png, image/jpeg, image/webp, application/pdf, text/plain이에요. 전체 MIME 타입을 지정하세요. image 같은 최상위 타입만으로는 GCS 툴 결과에 충분하지 않아요.

툴의 toModelOutput 결과에서 파일 파트를 사용하세요:

toModelOutput: ({ output }) => ({
  type: 'content',
  value: [
    {
      type: 'file',
      mediaType: 'image/png',
      data: {
        type: 'url',
        url: new URL(output.gcsUri),
        originalUrl: output.gcsUri,
      },
    },
  ],
}),

URL 파싱이 공백이 포함된 경로 같은 불투명한 GCS URI를 변경할 때는 originalUrl을 포함해서 Vertex가 정확한 객체 참조를 받도록 하세요. Vertex 호출자는 참조된 객체에 대한 접근 권한이 있어야 해요.

HTTP(S) 툴 결과 파일은 다운로드되어 toolResultDownloads.maxBytes의 적용을 받는 인라인 데이터로 전송돼요. GCS 툴 결과 직접 전달은 구형 Gemini 모델이나 위 목록에 없는 MIME 타입에서는 지원되지 않아요.

캐시된 콘텐츠 (Cached Content)

Google Vertex AI는 반복적인 콘텐츠의 비용을 줄이기 위해 명시적 및 암시적 캐싱을 모두 지원해요.

암시적 캐싱 (Implicit Caching)

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateText } from 'ai';

// Structure prompts with consistent content at the beginning
const baseContext =
  'You are a cooking assistant with expertise in Italian cuisine. Here are 1000 lasagna recipes for reference...';

const { text: veggieLasagna } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: `${baseContext}\n\nWrite a vegetarian lasagna recipe for 4 people.`,
});

// Second request with same prefix - eligible for cache hit
const { text: meatLasagna, providerMetadata } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: `${baseContext}\n\nWrite a meat lasagna recipe for 12 people.`,
});

// Check cached token count in usage metadata
console.log('Cached tokens:', providerMetadata.vertex);
// e.g.
// {
//   groundingMetadata: null,
//   safetyRatings: null,
//   usageMetadata: {
//     cachedContentTokenCount: 2027,
//     thoughtsTokenCount: 702,
//     promptTokenCount: 2152,
//     candidatesTokenCount: 710,
//     totalTokenCount: 3564
//   }
// }

명시적 캐싱 (Explicit Caching)

Gemini 모델에서 명시적 캐싱을 사용할 수 있어요. 모델이 캐싱을 지원하는지 확인하려면 Vertex AI 컨텍스트 캐싱 문서를 참고하세요.

먼저 Vertex 모드가 활성화된 Google GenAI SDK로 캐시를 만들어요:

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_VERTEX_PROJECT,
  location: process.env.GOOGLE_VERTEX_LOCATION,
});

const model = 'gemini-3.1-pro-preview';

// Create a cache with the content you want to reuse
const cache = await ai.caches.create({
  model,
  config: {
    contents: [
      {
        role: 'user',
        parts: [{ text: '1000 Lasagna Recipes...' }],
      },
    ],
    ttl: '300s', // Cache expires after 5 minutes
  },
});

console.log('Cache created:', cache.name);
// e.g. projects/my-project/locations/us-central1/cachedContents/abc123

그런 다음 AI SDK로 캐시를 사용해요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText } from 'ai';

const { text: veggieLasagnaRecipe } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
  providerOptions: {
    vertex: {
      cachedContent: cache.name,
    } satisfies GoogleLanguageModelOptions,
  },
});

const { text: meatLasagnaRecipe } = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  prompt: 'Write a meat lasagna recipe for 12 people.',
  providerOptions: {
    vertex: {
      cachedContent: cache.name,
    } satisfies GoogleLanguageModelOptions,
  },
});

안전 등급 (Safety Ratings)

안전 등급은 모델 응답의 안전성에 대한 통찰을 제공해요. 안전 필터 구성에 관한 Google Vertex AI 문서를 참고하세요.

응답 예시 일부:

{
  "safetyRatings": [
    {
      "category": "HARM_CATEGORY_HATE_SPEECH",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.11027937,
      "severity": "HARM_SEVERITY_LOW",
      "severityScore": 0.28487435
    },
    {
      "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
      "probability": "HIGH",
      "blocked": true,
      "probabilityScore": 0.95422274,
      "severity": "HARM_SEVERITY_MEDIUM",
      "severityScore": 0.43398145
    },
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.11085559,
      "severity": "HARM_SEVERITY_NEGLIGIBLE",
      "severityScore": 0.19027223
    },
    {
      "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
      "probability": "NEGLIGIBLE",
      "probabilityScore": 0.22901751,
      "severity": "HARM_SEVERITY_NEGLIGIBLE",
      "severityScore": 0.09089675
    }
  ]
}

자세한 내용은 Google Search로 접지하는 Google Vertex AI 문서를 참고하세요.

트러블슈팅 (Troubleshooting)

스키마 제한 (Schema Limitations)

Google Vertex API는 OpenAPI 3.0 스키마의 일부를 사용하는데, union 같은 기능을 지원하지 않아요. 이 경우 발생하는 오류는 다음과 같아요:

GenerateContentRequest.generation_config.response_schema.properties[occupation].type: must be specified

기본적으로 구조화된 출력이 활성화되어 있고(툴 호출에는 필수) 객체 생성을 위해 구조화된 출력을 비활성화할 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { type GoogleLanguageModelOptions } from '@ai-sdk/google';
import { generateText, Output } from 'ai';

const result = await generateText({
  model: googleVertex('gemini-3.1-pro-preview'),
  providerOptions: {
    vertex: {
      structuredOutputs: false,
    } satisfies GoogleLanguageModelOptions,
  },
  output: Output.object({
    schema: z.object({
      name: z.string(),
      age: z.number(),
      contact: z.union([
        z.object({
          type: z.literal('email'),
          value: z.string(),
        }),
        z.object({
          type: z.literal('phone'),
          value: z.string(),
        }),
      ]),
    }),
  }),
  prompt: 'Generate an example person for testing.',
});

Google Vertex에서 동작하지 않는 것으로 알려진 Zod 기능은 다음과 같아요:

• z.union
• z.record

모델 기능 (Model Capabilities)

임베딩 모델 (Embedding Models)

.embeddingModel() 팩토리 메서드로 Google Vertex AI 임베딩 API를 호출하는 모델을 만들 수 있어요:

const model = googleVertex.embeddingModel('text-embedding-005');

Google Vertex AI 임베딩 모델은 추가 설정을 지원해요. 옵션 인자로 전달할 수 있어요:

import {
  googleVertex,
  type GoogleVertexEmbeddingModelOptions,
} from '@ai-sdk/google-vertex';
import { embed } from 'ai';

const model = googleVertex.embeddingModel('text-embedding-005');

const { embedding } = await embed({
  model,
  value: 'sunny day at the beach',
  providerOptions: {
    vertex: {
      outputDimensionality: 512, // optional, number of dimensions for the embedding
      taskType: 'SEMANTIC_SIMILARITY', // optional, specifies the task type for generating embeddings
      autoTruncate: false, // optional
    } satisfies GoogleVertexEmbeddingModelOptions,
  },
});

Google Vertex AI 임베딩 모델에 사용할 수 있는 선택적 프로바이더 옵션은 다음과 같아요:

• outputDimensionality: number

  선택 사항이에요. 출력 임베딩의 축소 차원이에요. 설정하면 출력 임베딩에서 초과 값이 끝에서 잘려요.

• taskType: string

  선택 사항이에요. 임베딩 생성을 위한 작업 유형을 지정해요. 지원되는 작업 유형:

  • SEMANTIC_SIMILARITY: 텍스트 유사도에 최적화.
  • CLASSIFICATION: 텍스트 분류에 최적화.
  • CLUSTERING: 유사도 기반 텍스트 클러스터링에 최적화.
  • RETRIEVAL_DOCUMENT: 문서 검색에 최적화.
  • RETRIEVAL_QUERY: 쿼리 기반 검색에 최적화.
  • QUESTION_ANSWERING: 질문 답변에 최적화.
  • FACT_VERIFICATION: 사실 정보 검증에 최적화.
  • CODE_RETRIEVAL_QUERY: 자연어 쿼리 기반 코드 블록 검색에 최적화.

• title: string

  선택 사항이에요. 임베딩되는 문서의 제목이에요. 추가 컨텍스트를 제공해 모델이 더 나은 임베딩을 생성하도록 도와줘요. taskType이 'RETRIEVAL_DOCUMENT'로 설정된 경우에만 유효해요.

• autoTruncate: boolean

  선택 사항이에요. true로 설정하면 입력 텍스트가 최대 길이를 초과할 때 잘려요. false로 설정하면 입력 텍스트가 너무 길 때 오류가 반환돼요. 기본값은 true예요.

모델 기능 (Model Capabilities)

이미지 모델 (Image Models)

.image() 팩토리 메서드로 Gemini 이미지 모델을 만들 수 있어요. 이 모델들은 언어 모델 :generateContent API를 통해 이미지 출력을 제공해요. AI SDK에서 이미지 생성에 대해 더 알고 싶다면 generateImage()를 참고하세요.

Gemini 이미지 모델 (Gemini Image Models)

Gemini 이미지 모델(예: gemini-3.1-flash-image-preview)은 멀티모달 출력 언어 모델로, 더 간단한 이미지 생성 경험을 위해 generateImage()와 함께 사용할 수 있어요. 내부적으로 프로바이더는 responseModalities: ['IMAGE']로 언어 모델 API를 호출해요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: googleVertex.image('gemini-3.1-flash-image-preview'),
  prompt: 'A photorealistic image of a cat wearing a wizard hat',
  aspectRatio: '1:1',
});

Gemini 이미지 모델은 입력 이미지를 제공하여 이미지 편집도 지원해요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateImage } from 'ai';
import fs from 'node:fs';

const sourceImage = fs.readFileSync('./cat.png');

const { image } = await generateImage({
  model: googleVertex.image('gemini-3.1-flash-image-preview'),
  prompt: {
    text: 'Add a small wizard hat to this cat',
    images: [sourceImage],
  },
});

Gemini 이미지 모델 기능 (Gemini Image Model Capabilities)

비디오 모델 (Video Models)

.video() 팩토리 메서드로 Vertex AI API를 호출하는 Veo 비디오 모델을 만들 수 있어요. AI SDK에서 비디오 생성에 대해 더 알고 싶다면 generateVideo()를 참고하세요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: googleVertex.video('veo-3.1-generate-001'),
  prompt:
    'A pangolin curled on a mossy stone in a glowing bioluminescent forest',
  aspectRatio: '16:9',
});

해상도와 지속 시간을 구성할 수 있어요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: googleVertex.video('veo-3.1-generate-001'),
  prompt: 'A serene mountain landscape at sunset',
  aspectRatio: '16:9',
  resolution: '1920x1080',
  duration: 8,
});

첫 번째 및 마지막 프레임 (First and Last Frame)

Veo는 최상위 frameImages 옵션을 통해 첫-마지막 프레임 생성을 지원해요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: googleVertex.video('veo-3.1-generate-001'),
  prompt:
    'A hand reaches in and places a glass of milk next to the plate of cookies',
  frameImages: [
    {
      image: 'gs://cloud-samples-data/generative-ai/image/cookies.png',
      frameType: 'first_frame',
    },
    {
      image: 'gs://cloud-samples-data/generative-ai/image/cookies-milk.png',
      frameType: 'last_frame',
    },
  ],
  duration: 8,
});

참조 이미지 (Reference Images)

Veo 3.1은 최상위 inputReferences 옵션을 통해 참조-영상(reference-to-video) 생성을 지원해요:

import { googleVertex } from '@ai-sdk/google-vertex';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: googleVertex.video('veo-3.1-generate-001'),
  prompt:
    'The video opens with a medium shot of a woman in a high-fashion flamingo dress walking through a lagoon',
  inputReferences: [
    'gs://bucket/dress.png',
    'gs://bucket/glasses.png',
    'gs://bucket/woman.png',
  ],
  duration: 8,
});

프로바이더 옵션 (Provider Options)

Google Vertex 프로바이더 옵션으로 추가 구성을 할 수 있어요. GoogleVertexVideoModelOptions 타입으로 프로바이더 옵션을 검증할 수 있어요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { GoogleVertexVideoModelOptions } from '@ai-sdk/google-vertex';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: googleVertex.video('veo-3.1-generate-001'),
  prompt: 'A serene mountain landscape at sunset',
  aspectRatio: '16:9',
  providerOptions: {
    vertex: {
      generateAudio: true,
      personGeneration: 'allow_adult',
    } satisfies GoogleVertexVideoModelOptions,
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

• generateAudio boolean

  비디오와 함께 오디오를 생성할지 여부예요.

• personGeneration 'dont_allow' | 'allow_adult' | 'allow_all'

  비디오에서 사람 생성을 허용할지 여부예요.

• negativePrompt string

  생성된 비디오에서 피하고 싶은 내용에 대한 설명이에요.

• gcsOutputDirectory string

  생성된 비디오를 저장할 Cloud Storage URI예요.

• referenceImages Array<{ bytesBase64Encoded?: string; gcsUri?: string }>

  스타일 또는 자산 안내를 위한 참조 이미지예요.

• pollIntervalMs number

  작업 상태 확인을 위한 폴링 간격(밀리초)이에요.

• pollTimeoutMs number

  비디오 생성을 위한 최대 대기 시간(밀리초)이에요.

모델 기능 (Model Capabilities)

음성 모델 (Speech Models)

.speech() 팩토리 메서드로 Vertex AI API를 호출하는 Gemini 텍스트-음성 모델을 만들 수 있어요. AI SDK에서 음성 생성에 대해 더 알고 싶다면 generateSpeech()를 참고하세요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: googleVertex.speech('gemini-2.5-flash-tts'),
  text: 'Hello, world!',
  voice: 'Kore', // Gemini voice name
});

voice 인자는 Gemini의 사전 제작된 30개 음성 중 하나를 받아요(예: Kore, Puck, Zephyr). 기본값은 Kore예요. 다중 화자 대화는 providerOptions.googleVertex.multiSpeakerVoiceConfig를 통해 사용할 수 있어요.

기본적으로 오디오는 재생 가능한 WAV로 반환돼요(Gemini는 원시 PCM을 반환하며, 프로바이더가 이를 감쌈). 원시 부호 있는 16비트 리틀엔디언 모노 바이트를 원하면 outputFormat: 'pcm'을 설정하세요. 샘플레이트는 result.providerMetadata.google.sampleRate에 보고돼요.

음성 모델 기능 (Speech Model Capabilities)

음성 인식 모델 (Transcription Models)

.transcription() 팩토리 메서드를 transcribe()와 함께 사용하면 Google Cloud Speech-to-Text 모델로 오디오를 전사(transcribe)할 수 있어요.

import { googleVertex } from '@ai-sdk/google-vertex';
import { transcribe } from 'ai';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: googleVertex.transcription('chirp_2'),
  audio: await readFile('audio.wav'),
});

프로바이더는 Chirp 모델 chirp_2와 chirp_3, 그리고 전화 통화 오디오용 telephony를 지원해요. Speech-to-Text는 표준 Google Cloud 자격 증명(OAuth, Application Default Credentials 또는 서비스 계정)을 사용하며 Cloud Speech-to-Text API를 호출해요. 음성 인식 모델에서는 Express Mode API 키가 지원되지 않아요. GOOGLE_VERTEX_LOCATION(또는 providerOptions.googleVertex.region)을 Speech-to-Text 지역으로 설정하세요. Chirp의 경우 chirp_2는 us-central1, europe-west4, asia-southeast1에서, chirp_3는 us와 eu 다중 지역에서 사용할 수 있어요. Chirp는 global Speech-to-Text 위치에서 사용할 수 없으며, 이 지역들은 Vertex AI 지역과 다르다는 점에 유의하세요. telephony 가용성은 선택한 Speech-to-Text 지역과 언어에 따라 달라요.

동기 API는 1분 또는 10MB 중 먼저 도달하는 기준으로 오디오를 전사해요. 기본적으로 말하는 언어가 자동 감지되며, languageCodes를 전달해 제한할 수 있어요. telephony의 경우 ['en-US'] 같은 지원되는 언어 코드를 전달하세요.

const result = await transcribe({
  model: googleVertex.transcription('chirp_3'),
  audio: await readFile('audio.wav'),
  providerOptions: {
    googleVertex: {
      region: 'us',
      languageCodes: ['en-US'],
    },
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

• languageCodes string[]

  인식할 BCP-47 언어 코드이거나, 말하는 언어를 감지할 ['auto']예요. 기본값은 ['auto']예요. 여러 명시적 언어 코드에는 us나 eu 같은 다중 지역 Speech-to-Text 엔드포인트가 필요해요.

• enableAutomaticPunctuation boolean

  트랜스크립트에 구두점을 추가할지 여부예요. 기본값은 true예요.

• enableWordTimeOffsets boolean

  result.segments에 단어 수준 타임스탬프를 포함할지 여부예요. 기본값은 true예요. Google은 단어 수준 타임스탬프를 활성화하면 전사 품질과 속도가 저하될 수 있다고 언급해요.

• region string

  요청에 대한 Speech-to-Text 지역이에요. 기본값은 프로바이더 location이에요.

음성 인식 모델 기능 (Transcription Model Capabilities)

Google Vertex Anthropic 프로바이더 사용법 (Google Vertex Anthropic Provider Usage)

AI SDK용 Google Vertex Anthropic 프로바이더는 Google Vertex AI API를 통한 Anthropic의 Claude 모델 지원을 제공해요. 이 섹션에서는 Google Vertex Anthropic 프로바이더를 설정하고 사용하는 방법을 설명해요.

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/google-vertex/anthropic에서 기본 프로바이더 인스턴스 vertexAnthropic을 불러올 수 있어요:

import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic';

커스터마이즈가 필요하다면 @ai-sdk/google-vertex/anthropic에서 createVertexAnthropic을 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic';

const vertexAnthropic = createVertexAnthropic({
  project: 'my-project', // optional
  location: 'us-central1', // optional
});

Node.js 런타임

Node.js 환경의 경우 Google Vertex Anthropic 프로바이더는 google-auth-library를 통해 모든 표준 Google Cloud 인증 옵션을 지원해요. createVertexAnthropic 함수에 인증 옵션을 전달해 커스터마이즈할 수 있어요:

import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic';

const vertexAnthropic = createVertexAnthropic({
  googleAuthOptions: {
    credentials: {
      client_email: 'my-email',
      private_key: 'my-private-key',
    },
  },
});

선택적 프로바이더 설정 (Optional Provider Settings)

Google Vertex Anthropic 프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• project string

  API 호출에 사용할 Google Cloud 프로젝트 ID예요. 기본적으로 GOOGLE_VERTEX_PROJECT 환경 변수를 사용해요.

• location string

  API 호출에 사용할 Google Cloud 위치예요. 예: us-central1. 기본적으로 GOOGLE_VERTEX_LOCATION 환경 변수를 사용해요.

• googleAuthOptions object

  선택 사항이에요. Google Auth Library가 사용하는 인증 옵션이에요. GoogleAuthOptions 인터페이스도 참고하세요.

  • authClient object 사용할 AuthClient예요.

  • keyFilename string .json, .pem 또는 .p12 키 파일 경로예요.

  • keyFile string .json, .pem 또는 .p12 키 파일 경로예요.

  • credentials object client_email과 private_key 속성, 또는 외부 계정 클라이언트 옵션을 담은 객체예요.

  • clientOptions object 클라이언트의 생성자에 전달되는 옵션 객체예요.

  • scopes string | string[] 원하는 API 요청에 필요한 스코프예요.

  • projectId string 프로젝트 ID예요.

  • universeDomain string 주어진 Cloud universe의 기본 서비스 도메인이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요. 여러 형식으로 제공할 수 있어요:

  • 헤더 키-값 쌍 레코드: Record<string, string | undefined>
  • 헤더를 반환하는 함수: () => Record<string, string | undefined>
  • 헤더를 반환하는 async 함수: async () => Record<string, string | undefined>
  • 헤더로 해석되는 프로미스: Promise<Record<string, string | undefined>>

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

Edge 런타임

Edge 런타임(예: Cloudflare Workers)은 네트워크 엣지에서 사용자에 더 가깝게 실행되는 가벼운 JavaScript 환경이에요. 표준 Node.js API의 일부만 제공해요. 예를 들어 직접적인 파일 시스템 접근은 불가능하고, (표준 Google Auth 라이브러리를 포함한) 많은 Node.js 전용 라이브러리는 호환되지 않아요.

Google Vertex Anthropic 프로바이더의 Edge 런타임 버전은 환경 변수를 통한 Google의 Application Default Credentials를 지원해요. 값은 Google Cloud Console의 json 자격 증명 파일에서 얻을 수 있어요.

Edge 런타임의 경우 @ai-sdk/google-vertex/anthropic/edge에서 프로바이더 인스턴스를 불러올 수 있어요:

import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic/edge';

설정을 커스터마이즈하려면 같은 모듈에서 createVertexAnthropic을 사용하세요:

import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic/edge';

const vertexAnthropic = createVertexAnthropic({
  project: 'my-project', // optional
  location: 'us-central1', // optional
});

Edge 런타임 인증을 위해서는 Google Default Application Credentials JSON 파일에서 다음 환경 변수를 설정하세요:

• GOOGLE_CLIENT_EMAIL
• GOOGLE_PRIVATE_KEY
• GOOGLE_PRIVATE_KEY_ID (선택)

선택적 프로바이더 설정 (Optional Provider Settings)

프로바이더 인스턴스를 커스터마이즈할 때 사용할 수 있는 선택적 설정은 다음과 같아요:

• project string

  API 호출에 사용할 Google Cloud 프로젝트 ID예요. 기본적으로 GOOGLE_VERTEX_PROJECT 환경 변수를 사용해요.

• location string

  API 호출에 사용할 Google Cloud 위치예요. 예: us-central1. 기본적으로 GOOGLE_VERTEX_LOCATION 환경 변수를 사용해요.

• googleCredentials object

  선택 사항이에요. Edge 프로바이더가 인증에 사용하는 자격 증명이에요. 일반적으로 환경 변수로 설정되며 서비스 계정 JSON 파일에서 파생돼요.

  • clientEmail string 서비스 계정 JSON 파일의 클라이언트 이메일이에요. 기본값은 GOOGLE_CLIENT_EMAIL 환경 변수의 내용이에요.

  • privateKey string 서비스 계정 JSON 파일의 개인 키예요. 기본값은 GOOGLE_PRIVATE_KEY 환경 변수의 내용이에요.

  • privateKeyId string 서비스 계정 JSON 파일의 개인 키 ID예요(선택). 기본값은 GOOGLE_PRIVATE_KEY_ID 환경 변수의 내용이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요. 여러 형식으로 제공할 수 있어요:

  • 헤더 키-값 쌍 레코드: Record<string, string | undefined>
  • 헤더를 반환하는 함수: () => Record<string, string | undefined>
  • 헤더를 반환하는 async 함수: async () => Record<string, string | undefined>
  • 헤더로 해석되는 프로미스: Promise<Record<string, string | undefined>>

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 쓸 수도 있고, 예를 들어 테스트용으로 커스텀 fetch 구현을 제공할 수도 있어요.

언어 모델 (Language Models)

프로바이더 인스턴스로 Anthropic Messages API를 호출하는 모델을 만들 수 있어요. 첫 번째 인자는 모델 id예요. 예: claude-sonnet-5. 일부 모델은 멀티모달 기능을 가져요.

const model = vertexAnthropic('claude-sonnet-5');

generateText 함수로 Anthropic 언어 모델을 사용해 텍스트를 생성할 수 있어요:

import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic';
import { generateText } from 'ai';

const { text } = await generateText({
  model: vertexAnthropic('claude-sonnet-5'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Anthropic 언어 모델은 streamText 함수에서도 사용할 수 있고 Output으로 구조화된 데이터 생성을 지원해요 (AI SDK Core 참고).

Anthropic 모델에 사용할 수 있는 선택적 프로바이더 옵션은 다음과 같아요:

• sendReasoning boolean

  선택 사항이에요. 모델에 보내는 요청에 reasoning 콘텐츠를 포함할지 여부예요. 기본값은 true예요.

  모델이 reasoning 콘텐츠가 포함된 요청을 처리하는 데 문제가 있는 경우 false로 설정해 요청에서 제외할 수 있어요.

• thinking object

  선택 사항이에요. 자세한 내용은 Reasoning 섹션을 참고하세요.

• metadata object

  선택 사항이에요. 요청에 포함할 메타데이터예요. 자세한 내용은 Anthropic API 문서를 참고하세요.

  • userId string - 최종 사용자의 외부 식별자예요.

Reasoning

Anthropic은 claude-3-7-sonnet@20250219 모델에 대한 reasoning 지원을 제공해요.

thinking 프로바이더 옵션을 사용하고 토큰 단위의 thinking 예산을 지정해 활성화할 수 있어요.

import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic';
import { generateText } from 'ai';

const { text, reasoningText, reasoning } = await generateText({
  model: vertexAnthropic('claude-3-7-sonnet@20250219'),
  prompt: 'How many people will live in the world in 2040?',
  providerOptions: {
    anthropic: {
      thinking: { type: 'enabled', budgetTokens: 12000 },
    },
  },
});

console.log(reasoningText); // reasoning text
console.log(reasoning); // reasoning details including redacted reasoning
console.log(text); // text response

챗봇에 reasoning을 통합하는 방법에 대한 자세한 내용은 AI SDK UI: Chatbot을 참고하세요.

캐시 제어 (Cache Control)

messages와 message 파트에서 providerOptions 속성을 사용해 캐시 제어 중단점을 설정할 수 있어요. 캐시 제어 중단점을 설정하려면 providerOptions 객체의 anthropic 속성을 { cacheControl: { type: 'ephemeral' } }으로 설정해야 해요.

캐시 읽기 및 캐시 쓰기(생성) 토큰 수는 generateText와 streamText 모두에서 표준 usage 객체에 반환돼요. result.usage.inputTokenDetails.cacheReadTokens와 result.usage.inputTokenDetails.cacheWriteTokens에서 접근할 수 있어요.

import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic';
import { generateText } from 'ai';

const errorMessage = '... long error message ...';

const result = await generateText({
  model: vertexAnthropic('claude-sonnet-5'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'You are a JavaScript expert.' },
        {
          type: 'text',
          text: `Error message: ${errorMessage}`,
          providerOptions: {
            anthropic: { cacheControl: { type: 'ephemeral' } },
          },
        },
        { type: 'text', text: 'Explain the error message.' },
      ],
    },
  ],
});

console.log(result.text);
console.log(
  'Cache read tokens:',
  result.usage.inputTokenDetails.cacheReadTokens,
);
console.log(
  'Cache write tokens:',
  result.usage.inputTokenDetails.cacheWriteTokens,
);

messages 배열의 맨 앞에 여러 system 메시지를 제공해 system 메시지에도 캐시 제어를 사용할 수 있어요:

const result = await generateText({
  model: vertexAnthropic('claude-sonnet-5'),
  messages: [
    {
      role: 'system',
      content: 'Cached system message part',
      providerOptions: {
        anthropic: { cacheControl: { type: 'ephemeral' } },
      },
    },
    {
      role: 'system',
      content: 'Uncached system message part',
    },
    {
      role: 'user',
      content: 'User prompt',
    },
  ],
});

Anthropic 프롬프트 캐싱에 대한 자세한 내용은 Google Vertex AI의 Claude 프롬프트 캐싱 문서와 Anthropic의 캐시 제어 문서를 참고하세요.

툴 (Tools)

Google Vertex Anthropic은 Anthropic 내장 툴의 일부를 지원해요. 프로바이더 인스턴스의 tools 속성을 통해 다음 툴을 사용할 수 있어요:

1. Bash 툴: bash 명령 실행을 허용해요.
2. Text Editor 툴: 텍스트 파일 보기 및 편집 기능을 제공해요.
3. Computer 툴: 컴퓨터에서 키보드와 마우스 동작 제어를 가능하게 해요.
4. Web Search 툴: 실시간 웹 콘텐츠에 대한 접근을 제공해요.

Anthropic 툴에 대한 배경 지식은 Anthropic 문서를 참고하세요.

Bash 툴

Bash 툴은 bash 명령 실행을 허용해요. 만들고 사용하는 방법은 다음과 같아요:

const bashTool = vertexAnthropic.tools.bash_20250124({
  execute: async ({ command, restart }) => {
    // Implement your bash command execution logic here
    // Return the result of the command execution
  },
});

파라미터:

• command (string): 실행할 bash 명령이에요. 툴이 재시작 중이 아닌 한 필수예요.
• restart (boolean, 선택): true를 지정하면 이 툴을 재시작해요.

Text Editor 툴

Text Editor 툴은 텍스트 파일 보기 및 편집 기능을 제공해요:

const textEditorTool = vertexAnthropic.tools.textEditor_20250124({
  execute: async ({
    command,
    path,
    file_text,
    insert_line,
    new_str,
    insert_text,
    old_str,
    view_range,
  }) => {
    // Implement your text editing logic here
    // Return the result of the text editing operation
  },
});

파라미터:

• command ('view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'): 실행할 명령이에요. 참고: undo_edit는 textEditor_20250429와 textEditor_20250728에서 지원되지 않아요.
• path (string): 파일 또는 디렉터리의 절대 경로예요. 예: /repo/file.py 또는 /repo.
• file_text (string, 선택): create 명령에 필수이며, 생성할 파일의 내용이에요.
• insert_line (number, 선택): insert 명령에 필수예요. 새 문자열을 삽입할 이후의 줄 번호예요.
• new_str (string, 선택): str_replace 명령의 새 문자열이에요.
• insert_text (string, 선택): insert 명령에 필수이며, 삽입할 텍스트를 포함해요.
• old_str (string, 선택): str_replace 명령에 필수이며, 교체할 문자열을 포함해요.
• view_range (number[], 선택): view 명령에서 표시할 줄 범위를 지정하는 선택 항목이에요.
• max_characters (number, 선택): 파일에서 볼 수 있는 최대 문자 수(선택, textEditor_20250728에서만 사용 가능)예요.

Computer 툴

Computer 툴은 컴퓨터에서 키보드와 마우스 동작 제어를 가능하게 해요:

const computerTool = vertexAnthropic.tools.computer_20241022({
  displayWidthPx: 1920,
  displayHeightPx: 1080,
  displayNumber: 0, // Optional, for X11 environments

  execute: async ({ action, coordinate, text }) => {
    // Implement your computer control logic here
    // Return the result of the action

    // Example code:
    switch (action) {
      case 'screenshot': {
        // multipart result:
        return {
          type: 'image',
          data: fs
            .readFileSync('./data/screenshot-editor.png')
            .toString('base64'),
        };
      }
      default: {
        console.log('Action:', action);
        console.log('Coordinate:', coordinate);
        console.log('Text:', text);
        return `executed ${action}`;
      }
    }
  },

  // map to tool result content for LLM consumption:
  toModelOutput({ output }) {
    return typeof output === 'string'
      ? [{ type: 'text', text: output }]
      : [{ type: 'file-data', data: output.data, mediaType: 'image/png' }];
  },
});

파라미터:

• action ('key' | 'type' | 'mouse_move' | 'left_click' | 'left_click_drag' | 'right_click' | 'middle_click' | 'double_click' | 'screenshot' | 'cursor_position'): 수행할 동작이에요.
• coordinate (number[], 선택): mouse_move와 left_click_drag 동작에 필수예요. (x, y) 좌표를 지정해요.
• text (string, 선택): type과 key 동작에 필수예요.

Web Search 툴

Web Search 툴은 Claude에게 실시간 웹 콘텐츠에 대한 직접 접근을 제공해요:

const webSearchTool = vertexAnthropic.tools.webSearch_20250305({
  maxUses: 5, // Optional: Maximum number of web searches Claude can perform
  allowedDomains: ['example.com'], // Optional: Only search these domains
  blockedDomains: ['spam.com'], // Optional: Never search these domains
  userLocation: {
    // Optional: Provide location for geographically relevant results
    type: 'approximate',
    city: 'San Francisco',
    region: 'CA',
    country: 'US',
    timezone: 'America/Los_Angeles',
  },
});

파라미터:

• maxUses (number, 선택): 대화 중 Claude가 수행할 수 있는 웹 검색의 최대 횟수예요.
• allowedDomains (string[], 선택): Claude가 검색할 수 있는 도메인 목록(선택)이에요.
• blockedDomains (string[], 선택): Claude가 검색할 때 피해야 하는 도메인 목록(선택)이에요.
• userLocation (object, 선택): 지리적으로 관련된 검색 결과를 제공하기 위한 사용자 위치 정보(선택)예요.
  • type ('approximate'): 위치 유형(approximate여야 함)이에요.
  • city (string, 선택): 도시 이름이에요.
  • region (string, 선택): 지역 또는 주예요.
  • country (string, 선택): 국가예요.
  • timezone (string, 선택): IANA 시간대 ID예요.

이 툴들은 지원되는 Claude 모델과 함께 사용해 더 복잡한 상호작용과 작업을 가능하게 해요.

모델 기능 (Model Capabilities)

Vertex AI의 최신 Anthropic 모델 목록은 여기에서 확인할 수 있어요. Anthropic 모델 비교도 참고하세요.

Google Vertex xAI 프로바이더 사용법 (Google Vertex xAI Provider Usage)

Google Vertex xAI 프로바이더는 Google Vertex AI의 OpenAI 호환 Chat Completions API를 통해 xAI의 Grok 파트너 모델에 대한 지원을 제공해요.

자세한 내용은 Vertex AI Grok 문서를 참고하세요.

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/google-vertex/xai에서 기본 프로바이더 인스턴스 googleVertexXai를 불러올 수 있어요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai';

커스터마이즈가 필요하다면 @ai-sdk/google-vertex/xai에서 createGoogleVertexXai를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createGoogleVertexXai } from '@ai-sdk/google-vertex/xai';

const googleVertexXai = createGoogleVertexXai({
  project: 'my-project', // optional
  location: 'global', // optional, defaults to 'global'
});

Node.js 런타임

Node.js 환경의 경우 Google Vertex xAI 프로바이더는 google-auth-library를 통해 모든 표준 Google Cloud 인증 옵션을 지원해요:

import { createGoogleVertexXai } from '@ai-sdk/google-vertex/xai';

const googleVertexXai = createGoogleVertexXai({
  googleAuthOptions: {
    credentials: {
      client_email: 'my-email',
      private_key: 'my-private-key',
    },
  },
});

선택적 프로바이더 설정 (Optional Provider Settings)

• project string

  Google Cloud 프로젝트 ID예요. 기본값은 GOOGLE_VERTEX_PROJECT 환경 변수예요.

• location string

  Google Cloud 위치예요. Grok 모델은 global 엔드포인트에서 사용할 수 있어요. 기본값은 GOOGLE_VERTEX_LOCATION 환경 변수예요. 설정되지 않으면 기본값은 global이에요.

• googleAuthOptions object

  선택 사항이에요. Google Auth Library가 사용하는 인증 옵션이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요.

Edge 런타임

Edge 런타임의 경우 @ai-sdk/google-vertex/xai/edge에서 import 하세요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai/edge';

import { createGoogleVertexXai } from '@ai-sdk/google-vertex/xai/edge';

const googleVertexXai = createGoogleVertexXai({
  project: 'my-project',
  location: 'global',
});

Edge 런타임 인증을 위해 다음 환경 변수를 설정하세요:

• GOOGLE_CLIENT_EMAIL
• GOOGLE_PRIVATE_KEY
• GOOGLE_PRIVATE_KEY_ID (선택)

언어 모델 (Language Models)

프로바이더 인스턴스로 모델을 만들 수 있어요. 첫 번째 인자는 모델 ID예요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: googleVertexXai('xai/grok-4.1-fast-reasoning'),
  prompt: 'Invent a new holiday and describe its traditions.',
});

스트리밍도 지원돼요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai';
import { streamText } from 'ai';

const result = streamText({
  model: googleVertexXai('xai/grok-4.1-fast-reasoning'),
  prompt: 'Invent a new holiday and describe its traditions.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

함수 호출 (Function Calling)

Vertex의 Grok 모델은 OpenAI 호환 함수 호출을 지원해요. 평소처럼 AI SDK 툴을 사용할 수 있어요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: googleVertexXai('xai/grok-4.1-fast-reasoning'),
  tools: {
    weather: tool({
      description: 'Get the weather in a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => `The weather in ${city} is sunny.`,
    }),
  },
  prompt: 'What is the weather in San Francisco?',
});

구조화된 출력 (Structured Outputs)

Vertex의 Grok 모델은 JSON 모드와 스키마 기반 구조화된 출력을 지원해요:

import { googleVertexXai } from '@ai-sdk/google-vertex/xai';
import { generateText, Output } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: googleVertexXai('xai/grok-4.1-fast-reasoning'),
  output: Output.object({
    schema: z.object({
      name: z.string(),
      date: z.string(),
      participants: z.array(z.string()),
    }),
  }),
  prompt: 'Alice and Bob are going to a science fair on Friday.',
});

사용 가능한 모델 (Available Models)

Google Vertex xAI 프로바이더를 통해 다음 모델을 사용할 수 있어요. 유효한 모델 ID를 문자열로 전달할 수도 있어요.

Google Vertex MaaS 프로바이더 사용법 (Google Vertex MaaS Provider Usage)

Google Vertex MaaS(Model as a Service) 프로바이더는 OpenAI 호환 Chat Completions API를 통해 Vertex AI에 호스팅된 파트너 및 오픈 모델에 대한 접근을 제공해요. DeepSeek, Qwen, Meta, MiniMax, Moonshot, OpenAI의 모델이 포함돼요.

자세한 내용은 Vertex AI MaaS 문서를 참고하세요.

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/google-vertex/maas에서 기본 프로바이더 인스턴스 vertexMaas를 불러올 수 있어요:

import { vertexMaas } from '@ai-sdk/google-vertex/maas';

커스터마이즈가 필요하다면 @ai-sdk/google-vertex/maas에서 createVertexMaas를 불러와 원하는 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createVertexMaas } from '@ai-sdk/google-vertex/maas';

const vertexMaas = createVertexMaas({
  project: 'my-project', // optional
  location: 'us-east5', // optional, defaults to 'global'
});

Node.js 런타임

Node.js 환경의 경우 Google Vertex MaaS 프로바이더는 google-auth-library를 통해 모든 표준 Google Cloud 인증 옵션을 지원해요:

import { createVertexMaas } from '@ai-sdk/google-vertex/maas';

const vertexMaas = createVertexMaas({
  googleAuthOptions: {
    credentials: {
      client_email: 'my-email',
      private_key: 'my-private-key',
    },
  },
});

선택적 프로바이더 설정 (Optional Provider Settings)

• project string

  Google Cloud 프로젝트 ID예요. 기본값은 GOOGLE_VERTEX_PROJECT 환경 변수예요.

• location string

  Google Cloud 위치예요. 예: us-east5 또는 global. 기본값은 GOOGLE_VERTEX_LOCATION 환경 변수예요. 설정되지 않으면 기본값은 global이에요.

• googleAuthOptions object

  선택 사항이에요. Google Auth Library가 사용하는 인증 옵션이에요.

• headers Resolvable<Record<string, string | undefined>>

  요청에 포함할 헤더예요.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현이에요.

Edge 런타임

Edge 런타임의 경우 @ai-sdk/google-vertex/maas/edge에서 import 하세요:

import { vertexMaas } from '@ai-sdk/google-vertex/maas/edge';

import { createVertexMaas } from '@ai-sdk/google-vertex/maas/edge';

const vertexMaas = createVertexMaas({
  project: 'my-project',
  location: 'us-east5',
});

Edge 런타임 인증을 위해 다음 환경 변수를 설정하세요:

• GOOGLE_CLIENT_EMAIL
• GOOGLE_PRIVATE_KEY
• GOOGLE_PRIVATE_KEY_ID (선택)

언어 모델 (Language Models)

프로바이더 인스턴스로 모델을 만들 수 있어요. 첫 번째 인자는 모델 ID예요:

import { vertexMaas } from '@ai-sdk/google-vertex/maas';
import { generateText } from 'ai';

const { text } = await generateText({
  model: vertexMaas('deepseek-ai/deepseek-v3.2-maas'),
  prompt: 'Invent a new holiday and describe its traditions.',
});

스트리밍도 지원돼요:

import { vertexMaas } from '@ai-sdk/google-vertex/maas';
import { streamText } from 'ai';

const result = streamText({
  model: vertexMaas('deepseek-ai/deepseek-v3.2-maas'),
  prompt: 'Invent a new holiday and describe its traditions.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

사용 가능한 모델 (Available Models)

MaaS 프로바이더를 통해 다음 모델을 사용할 수 있어요. 유효한 모델 ID를 문자열로 전달할 수도 있어요.

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵