Google Vertex AI

Gemini Developer API에는 리전 엔드포인트가 없습니다. EU 데이터 레지던시, CMEK 또는 VPC-SC가 필요하면 Vertex AI에서 Gemini를 실행해야 합니다.

@tanstack/ai-vertex가 그 방법을 제공합니다. 기존 Gemini 어댑터를 Vertex 인증과 함께 구성합니다. 요청 매핑, 도구, 스트리밍은 동일하게 유지됩니다.

Vertex의 Claude는 다른 패키지입니다. Anthropic Vertex를 참조하세요.

설치

npm install @tanstack/ai-vertex

기본 사용법

import { chat } from "@tanstack/ai";
import { vertexText } from "@tanstack/ai-vertex";

const stream = chat({
  adapter: vertexText("gemini-3.7-flash", {
    project: "my-project",
    location: "europe-west1",
  }),
  messages: [{ role: "user", content: "Hello!" }],
});

모든 팩토리에서 하나의 인증 객체를 재사용합니다.

import { vertexImage, vertexText } from "@tanstack/ai-vertex";

const auth = {
  project: "my-project",
  location: "europe-west1",
};

const text = vertexText("gemini-3.7-flash", auth);
const image = vertexImage("gemini-3.1-flash-image", auth);

인증

Vertex 팩토리는 @google/genai가 허용하는 모든 인증 옵션을 허용합니다. GEMINI_API_KEY 또는 GOOGLE_API_KEY는 읽지 않습니다. 이러한 키는 Vertex가 아니라 AI Studio용입니다.

애플리케이션 기본 자격 증명

일반적인 Google Cloud 경로입니다. gcloud auth application-default login으로 로그인하거나 GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 JSON 파일로 설정합니다.

팩토리에서 project와 location을 전달하거나 다음과 같이 설정합니다.

GOOGLE_CLOUD_PROJECT=my-project
GOOGLE_CLOUD_LOCATION=europe-west1

GOOGLE_VERTEX_PROJECT와 GOOGLE_VERTEX_LOCATION도 허용됩니다.

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  project: "my-project",
  location: "europe-west1",
});

서비스 계정 필드

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  project: "my-project",
  location: "europe-west1",
  googleAuthOptions: {
    credentials: {
      client_email: "sa@my-project.iam.gserviceaccount.com",
      private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    },
  },
});

Express API 키

Vertex Express 모드는 API 키를 사용하며 project나 location이 필요하지 않습니다.

import { vertexText } from "@tanstack/ai-vertex";

const adapter = vertexText("gemini-3.7-flash", {
  apiKey: "vertex-express-key",
});

또는 GOOGLE_VERTEX_API_KEY를 설정합니다.

예제: 서버와 클라이언트

Vertex 자격 증명은 서버에 보관합니다. 브라우저는 라우트와만 통신합니다.

서버:

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { vertexText } from "@tanstack/ai-vertex";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const stream = chat({
    adapter: vertexText("gemini-3.7-flash", {
      project: "my-project",
      location: "europe-west1",
    }),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

클라이언트:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

export function Chat() {
  const { messages, sendMessage } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
  });

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const form = event.currentTarget;
        const input = new FormData(form).get("text");
        if (typeof input === "string" && input.trim()) {
          sendMessage(input);
          form.reset();
        }
      }}
    >
      {messages.map((message) => (
        <div key={message.id}>
          {message.role}:{" "}
          {message.parts
            .filter((part) => part.type === "text")
            .map((part) => part.content)
            .join("")}
        </div>
      ))}
      <input name="text" />
      <button type="submit">Send</button>
    </form>
  );
}

useChat은 이것이 Vertex인지 알지 못합니다. 서버의 SSE 스트림만 소비합니다.

기타 Gemini 활동

모든 팩토리는 동일한 인증 객체를 사용합니다.

import {
  vertexAudio,
  vertexEmbedding,
  vertexImage,
  vertexSpeech,
  vertexSummarize,
  vertexText,
  vertexVideo,
} from "@tanstack/ai-vertex";

const auth = { project: "my-project", location: "europe-west1" };

vertexText("gemini-3.7-flash", auth);
vertexSummarize("gemini-3.7-flash", auth);
vertexImage("gemini-3.1-flash-image", auth);
vertexEmbedding("gemini-embedding-001", auth);
vertexSpeech("gemini-3.1-flash-tts-preview", auth);
vertexAudio("lyria-3-pro-preview", auth);
vertexVideo("veo-3.1-generate-preview", auth);

모델 ID와 provider 옵션은 @tanstack/ai-gemini와 동일합니다. Vertex 전용 이미지 옵션(예: 9:21)은 이 릴리스에서 활성화되지 않습니다.

환경 변수

변수	용도
GOOGLE_CLOUD_PROJECT	GCP 프로젝트 ID
GOOGLE_VERTEX_PROJECT	프로젝트 ID의 별칭
GOOGLE_CLOUD_LOCATION	리전(예: europe-west1)
GOOGLE_VERTEX_LOCATION	리전의 별칭
GOOGLE_VERTEX_API_KEY	Vertex Express API 키
GOOGLE_APPLICATION_CREDENTIALS	서비스 계정 JSON 파일 경로

API 레퍼런스

vertexText(model, config?)

Vertex에서 Gemini 채팅 어댑터를 생성합니다.

vertexSummarize(model, config?)

Vertex에서 Gemini 요약 어댑터를 생성합니다.

vertexImage(model, config?)

Vertex에서 Gemini 이미지 어댑터를 생성합니다.

vertexEmbedding(model, config?)

Vertex에서 Gemini 임베딩 어댑터를 생성합니다.

vertexSpeech(model, config?)

Vertex에서 Gemini 텍스트 음성 변환 어댑터를 생성합니다. 실험적 기능입니다.

vertexAudio(model, config?)

Vertex에서 Gemini Lyria 오디오 어댑터를 생성합니다. 실험적 기능입니다.

vertexVideo(model, config?)

Vertex에서 Gemini 동영상 어댑터를 생성합니다. 실험적 기능입니다. config.allowUrlFetch는 Gemini 동영상 어댑터와 동일한 옵트인 설정입니다.

config는 project, location, apiKey, googleAuthOptions, httpOptions 및 기타 @google/genai 클라이언트 필드를 허용합니다. 팩토리는 항상 vertexai: true를 설정합니다.

Vertex의 Claude

@tanstack/ai-anthropic/vertex에서 anthropicVertexText를 사용합니다.

Vertex의 Grok

@tanstack/ai-grok/vertex에서 grokVertexText를 사용합니다. Vertex Grok은 OpenAI 호환 Responses 엔드포인트를 사용합니다. 요약에는 같은 진입점의 grokVertexSummarize를 사용합니다. 팩토리는 Vertex 카탈로그의 Grok 채팅 모델(grok-4.3, grok-4.20-reasoning, grok-4.20-non-reasoning, grok-4.1-fast-reasoning, grok-4.1-fast-non-reasoning)만 허용합니다.

Vertex의 Mistral

@tanstack/ai-mistral/vertex에서 mistralVertexText를 사용합니다. Vertex Mistral은 publisher rawPredict 경로를 사용합니다. 리전 전용이며(us-central1 또는 europe-west4), 팩토리는 Vertex 카탈로그의 Mistral 채팅 모델(mistral-medium-3, mistral-small-2503, codestral-2)만 허용합니다.