본문으로 건너뛰기

LLM Gateway

LLM Gateway는 여러 프로바이더의 수백 개 모델로 하나의 OpenAI 호환 엔드포인트를 라우팅하는 오픈 소스 AI 게이트웨이입니다. 프로바이더 자동 선택, 폴백, 사용량 분석 및 비용 추적을 제공합니다. 호스팅된 게이트웨이 api.llmgateway.io를 사용하거나 어댑터가 자체 셀프 호스팅 배포를 가리키도록 설정할 수 있습니다.

설치​

npm install @tanstack/ai-llmgateway

기본 사용법​

import { chat } from "@tanstack/ai";
import { llmGatewayText } from "@tanstack/ai-llmgateway";

const stream = chat({
  adapter: llmGatewayText("gpt-5.6-terra"),
  messages: [{ role: "user", content: "Hello!" }],
});

llmGatewayText는 LLM_GATEWAY_API_KEY 환경 변수에서 API 키를 읽습니다. 명시적으로 전달하려면 createLLMGatewayText를 사용하세요.

구성​

import { createLLMGatewayText } from "@tanstack/ai-llmgateway";

const adapter = createLLMGatewayText(
  "gpt-5.6-terra",
  process.env.LLM_GATEWAY_API_KEY!,
  {
    baseURL: "https://api.llmgateway.io/v1", // Optional — set for self-hosted deployments
  },
);

LLM Gateway는 오픈 소스이며 셀프 호스팅할 수 있습니다. 동일한 어댑터 인터페이스를 유지하려면 baseURL이 자체 배포를 가리키도록 설정하세요.

사용 가능한 모델​

llmgateway.io/models에 나열된 모든 모델이 작동합니다. 해당 id를 모델 이름으로 전달하세요. 모델 id만 지정하면 게이트웨이가 가장 적합한 프로바이더로 라우팅하고, 특정 프로바이더로 라우팅을 고정하려면 provider/를 접두사로 추가하세요.

model: "gpt-5.6-terra"          // gateway picks the provider
model: "claude-sonnet-5"        // gateway picks the provider
model: "moonshot/kimi-k3"       // always routed to Moonshot
model: "fireworks/kimi-k3"      // always routed to Fireworks

엄선된 주요 모델 집합(LLMGATEWAY_CHAT_MODELS 참조)은 편집기 자동 완성과 함께 모델별 타입 메타데이터(입력 모달리티 및 프로바이더 옵션)도 제공합니다. 엄선되지 않은 id도 작동하며, 일반 옵션과 텍스트 전용 입력으로 대체됩니다.

예제: 채팅 완성​

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { llmGatewayText } from "@tanstack/ai-llmgateway";

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

  const stream = chat({
    adapter: llmGatewayText("gpt-5.6-terra"),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

예제: 도구 사용​

import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
import { llmGatewayText } from "@tanstack/ai-llmgateway";
import { z } from "zod";

const getWeatherDef = toolDefinition({
  name: "get_weather",
  description: "Get the current weather",
  inputSchema: z.object({
    location: z.string(),
  }),
});

const getWeather = getWeatherDef.server(async ({ location }) => {
  return { temperature: 72, conditions: "sunny" };
});

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

  const stream = chat({
    adapter: llmGatewayText("gpt-5.6-terra"),
    messages,
    tools: [getWeather],
  });

  return toServerSentEventsResponse(stream);
}

모델 옵션​

게이트웨이는 표준 Chat Completions 매개변수를 받아 라우팅된 프로바이더로 전달합니다(프로바이더가 지원하지 않는 매개변수는 서버 측에서 제거됩니다). 샘플링 매개변수는 modelOptions에 지정합니다.

import { chat } from "@tanstack/ai";
import { llmGatewayText } from "@tanstack/ai-llmgateway";

const stream = chat({
  adapter: llmGatewayText("kimi-k3"),
  messages: [{ role: "user", content: "Hello!" }],
  modelOptions: {
    temperature: 0.7,
    max_completion_tokens: 4096,
    reasoning_effort: "high",
  },
});

reasoning_effort는 OpenAI의 표준 단계 외에도 확장된 none / minimal / low / medium / high / xhigh / max 척도를 허용합니다. 어떤 단계가 적용되는지는 라우팅된 모델과 프로바이더에 따라 다릅니다(llmgateway.io/models의 모델 페이지를 참조하세요).

추론 모델은 사고 과정을 reasoning_content 델타로 스트리밍하며, 어댑터는 이를 AG-UI REASONING_* 이벤트로 노출합니다.

요약​

import { summarize } from "@tanstack/ai";
import { llmGatewaySummarize } from "@tanstack/ai-llmgateway";

const result = await summarize({
  adapter: llmGatewaySummarize("gpt-5.4-mini"),
  text: "Long article text...",
  stream: false,
});

console.log(result.summary);

환경 변수​

환경 변수에 API 키를 설정합니다.

LLM_GATEWAY_API_KEY=llmgtwy_your-api-key

LLM Gateway 대시보드에서 API 키를 발급받으세요.