LangChain OpenRouter Kurulumu: Base URL’ler, Araçlar ve Çözümler

Yeni LangChain uygulamalarında ChatOpenRouter kullanın. Yükseltilemeyen eski projelerde ChatOpenAI ile https://openrouter.ai/api/v1 adresini koruyun; https://openrouter.ai/api adresini ise yalnızca Anthropic Agent SDK akışında kullanın.

Kısa cevap: Yeni LangChain projelerinde native entegrasyonu tercih edin

OpenRouter model uç noktasını ve yönlendirme katmanını, LangChain ise sohbet modeli, zincir ve ajan soyutlamalarını sağlar. Güncel ve doğrudan entegrasyon Python’da langchain-openrouter ile ChatOpenRouter; JavaScript ve TypeScript’te ise @langchain/openrouter ile ChatOpenRouter şeklindedir.

LangChain’in birinci taraf paket duyurusuna göre native paket; reasoning içeriği, yapılandırılmış çıktı, yönlendirme metadata’sı ve izleme kimliği gibi OpenRouter’a özgü davranışları koruyor. Genel amaçlı bir ChatOpenAI sarmalayıcısı bu alanları kaybedebilir. Bu bilgiler uygulamanız için önemli değilse mevcut uyumluluk kurulumunu hemen yeniden yazmanız gerekmez.

Framework adından önce endpoint haritasını çıkarın

Farklı SDK’ler, yapılandırdığınız base URL’in sonuna farklı istek yolları ekler. OpenAI uyumlu rota https://openrouter.ai/api/v1 adresidir; OpenRouter OpenAI SDK rehberi de bu değeri kullanır. Buna karşılık Anthropic Agent SDK rehberi, ANTHROPIC_BASE_URL değerini https://openrouter.ai/api olarak ayarlar.

SDK açıkça tam endpoint istemediği sürece base URL içine /chat/completions eklemeyin. Hata mesajında /v1/v1 gibi yinelenen bir yol görüyorsanız SDK’nin base URL ile endpoint yolunu nasıl birleştirdiğini kontrol edin.

Eski OpenAI uyumlu LangChain istemcisi için çalışan en temel kurulum şöyledir:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-4o",
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1",
)

response = llm.invoke("Explain provider routing in one sentence.")
print(response.content)

OpenAI anahtarı değil, OpenRouter API anahtarı kullanın. OpenRouter’ın Hızlı Başlangıç dokümanı Bearer token kimlik doğrulamasını belirtir. HTTP-Referer ve X-OpenRouter-Title, isteğe bağlı uygulama tanımlama header’larıdır; Authorization header’ının alternatifi değildir.

LangChain + OpenRouter: güncel kurulum

Python: langchain-openrouter

Entegrasyonu yükleyin ve anahtarı kaynak kodunun dışında tutun:

pip install -U langchain-openrouter
export OPENROUTER_API_KEY="sk-or-..."

Ardından native sohbet modelini oluşturun. LangChain Python entegrasyonu, model, temperature, max_tokens ve max_retries parametrelerini bu biçimde belgeliyor:

from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    temperature=0,
    max_tokens=1024,
    max_retries=2,
)

response = model.invoke([
    ("system", "You are a concise technical assistant."),
    ("human", "What does OpenRouter add to a LangChain application?"),
])

print(response.content)

OpenRouter model adları genellikle provider/model biçimini kullanır. Örneğin anthropic/claude-sonnet-4.5, openai/gpt-4o veya deepseek/deepseek-r1. Dağıtıma çıkmadan önce OpenRouter Models API üzerinden kontrol yapın; model kimlikleri, alias’lar, varyantlar, erişilebilirlik ve desteklenen parametreler değişebilir.

JavaScript ve TypeScript: @langchain/openrouter

Entegrasyonu ve LangChain core paketini yükleyin:

npm install @langchain/openrouter @langchain/core

LangChain JavaScript entegrasyonundaki nesne tabanlı kurucu, Python örneğiyle karşılaştırmayı kolaylaştıran açık bir kullanım sunuyor:

import { ChatOpenRouter } from "@langchain/openrouter";

const model = new ChatOpenRouter({
  model: "anthropic/claude-sonnet-4.5",
  temperature: 0,
  maxTokens: 1024,
});

const response = await model.invoke([
  { role: "system", content: "You are a concise technical assistant." },
  { role: "user", content: "Explain the provider/model format." },
]);

console.log(response.content);

Python’da max_tokens, JavaScript örneğinde ise maxTokens kullanılır. Her iki entegrasyon da varsayılan olarak OPENROUTER_API_KEY değişkenini okur. Model katalogda görünüyor ancak kod içinde çalışmıyorsa tam slug’ı, varyant son ekini ve desteklenen istek parametrelerini kontrol edin.

init_chat_model ve sürüm tuzağı

Sık karşılaşılan hata mesajı şöyledir:

ValueError: Unsupported model_provider='openrouter'.

Bir LangChain Forum sorun giderme başlığı, bu durumun v1 dokümantasyonu kullanılırken v1 öncesi LangChain kurulmasından kaynaklanabileceğini belirtiyor. Önerilen çözüm, framework ile partner paketini birlikte yükseltmek:

pip install -U "langchain>=1" langchain-openrouter

Ardından genel başlatıcıyı kullanabilirsiniz:

import os
from langchain.chat_models import init_chat_model

os.environ["OPENROUTER_API_KEY"] = "sk-or-..."

model = init_chat_model(
    "anthropic/claude-sonnet-4.5",
    model_provider="openrouter",
)

print(model.invoke("Say hello in one sentence.").content)

Proje LangChain v1’e taşınamıyorsa langchain-openrouter paketini yükleyip doğrudan ChatOpenRouter oluşturun. Böylece genel sağlayıcı kayıt sistemini devre dışı bırakır ve OpenRouter bağımlılığını açıkça tanımlarsınız.

ChatOpenAI’den ChatOpenRouter’a geçiş

Kod değişikliği küçük olsa da entegrasyon sınırı genel bir OpenAI adaptöründen sağlayıcıya özel bir sınıfa taşınır:

# Before: OpenAI-compatible workaround
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="anthropic/claude-sonnet-4.5",
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

# After: native OpenRouter integration
from langchain_openrouter import ChatOpenRouter

model = ChatOpenRouter(model="anthropic/claude-sonnet-4.5")

Önce mevcut prompt ve zincir çağrılarını değiştirmeden koruyun. Temel native çağrı sorunsuz çalıştıktan sonra sağlayıcı yönlendirme, reasoning, yapılandırılmış çıktı veya metadata işlemesini ekleyin.

LangChain’de streaming, callback, araçlar ve yapılandırılmış çıktı

Basit metin tüketimi için model.stream() mesaj parçaları üretir. Callback tarzı loglama, arayüz durumu ve tracing için ise yaşam döngüsü olaylarını sunan stream_events(..., version="v3") daha uygundur. Her iki arayüz de LangChain Python entegrasyonunda belgeleniyor.

model = ChatOpenRouter(model="openai/gpt-4o")

for event in model.stream_events(
    "Explain why OpenRouter has provider fallbacks.",
    version="v3",
):
    if event["event"] == "on_chat_model_stream":
        chunk = event["data"]["chunk"]
        print(chunk.text, end="", flush=True)

Uygulamanın başlangıç, token, bitiş veya hata bildirimlerine ihtiyacı varsa callback kullanın. Yalnızca model parçalarını tüketiyorsanız stream() yeterlidir. Kullanım bilgilerini ve yanıt metadata’sını rastgele seçilmiş ilk chunk’tan değil, tamamlanmış yanıttan veya birleştirilmiş stream sonucundan okuyun.

Araç çağırma ve sağlayıcı yönlendirme

OpenRouter, normalize edilmiş bir araç çağırma akışı sunuyor: Model bir araç çağrısı önerir, uygulama bu aracı çalıştırır ve sonucu yeniden modele gönderir. ChatOpenRouter.bind_tools(); LangChain araçlarını, Python fonksiyonlarını, Pydantic sınıflarını ve sözlük tabanlı şemaları kabul eder.

from pydantic import BaseModel, Field

class GetWeather(BaseModel):
    """Get current weather for a city."""

    location: str = Field(
        description="City and state, for example San Francisco, CA"
    )

model_with_tools = model.bind_tools(
    [GetWeather],
    strict=True,
)

result = model_with_tools.invoke("What is the weather in San Francisco?")
print(result.tool_calls)

İlk çağrı yalnızca modelin önerdiği araç çağrılarını döndürür. Eksiksiz ve manuel bir gidiş-dönüş akışı için her çağrıdan önce bir ToolMessage oluşturup sonucu modele göndermeniz gerekir:

from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool

@tool
def get_weather(location: str) -> str:
    """Get the current weather in a location."""
    return f"Sunny in {location}."

model_with_tools = model.bind_tools([get_weather])
messages = [HumanMessage("What is the weather in San Francisco?")]
ai_msg = model_with_tools.invoke(messages)
messages.append(ai_msg)

for call in ai_msg.tool_calls:
    tool_output = get_weather.invoke(call["args"])
    messages.append(
        ToolMessage(
            content=tool_output,
            tool_call_id=call["id"],
        )
    )

final_msg = model_with_tools.invoke(messages)
print(final_msg.content)

Sağlayıcı yönlendirme, LangChain entegrasyonunda ve OpenRouter sağlayıcı yönlendirme rehberinde açıklanan OpenRouter’a özel model yapılandırması içinde yapılır:

routed_model = ChatOpenRouter(
    model="anthropic/claude-sonnet-4.5",
    openrouter_provider={
        "order": ["Anthropic", "Google"],
        "allow_fallbacks": True,
        "require_parameters": True,
        "data_collection": "deny",
    },
)

order tercih sırasını belirtir. only kullanılabilecek sağlayıcıları sınırlar, ignore ise belirli sağlayıcıları dışarıda bırakır. allow_fallbacks=True, isteğin tercih edilen sıranın dışındaki sağlayıcılara da gönderilmesine izin verebilir. require_parameters=True ise payload içindeki tüm parametreleri desteklemeyen sağlayıcıların kullanılmasını engeller. Bu ayarlar erişilebilirlik ile sağlayıcı üzerindeki kontrol arasında bir tercih yaratır.

Eski ChatOpenAI istemcilerinde OpenRouter’a özgü alanların, istemci sürümüne bağlı olarak extra_body veya model_kwargs üzerinden gönderilmesi gerekebilir. Bir kullanıcı, LangChain/OpenRouter Reddit başlığında şu soruyu sormuştu:

“Wondering, doesn't openrouter support the openai API spec such that the openai client works?” — u/tuxedo0.

Özel paket, her sağlayıcıya özgü alanı genel bir OpenAI sarmalayıcısına taşıma zorunluluğunu ortadan kaldırarak OpenRouter entegrasyon sınırını netleştirir.

Yapılandırılmış çıktı: yalnızca model adına değil, endpoint’e de bakın

Native entegrasyon, with_structured_output() üzerinden tip güvenli çıktı sunar. LangChain Python dokümantasyonu, native JSON Schema yöntemini şöyle gösteriyor:

from pydantic import BaseModel, Field

class Movie(BaseModel):
    title: str
    year: int
    director: str
    rating: float = Field(description="Rating from 0 to 10")

structured_model = ChatOpenRouter(
    model="openai/gpt-5.5",
).with_structured_output(
    Movie,
    method="json_schema",
    strict=True,
)

movie = structured_model.invoke("Give details about the movie Inception.")
print(movie)

Entegrasyon function_calling yöntemini de belgeler; strict, json_mode ile desteklenmez. OpenRouter’ın yapılandırılmış çıktı davranışı sunucu endpoint’ine göre değişebilir. Bu nedenle yalnızca model adına bakarak destek garantisi vermeyin. OpenRouter yapılandırılmış çıktı rehberi, sağlayıcı yetenek kontrollerinin, require_parameters ayarının ve istemci tarafı doğrulamanın neden önemli olduğunu açıklıyor.

Vercel AI SDK + OpenRouter

Vercel AI SDK kullanan bir Next.js veya TypeScript uygulaması için OpenRouter sağlayıcısını yükleyin:

npm install @openrouter/ai-sdk-provider ai zod

Bu kısa örnek, metin streaming’ini ve yerel bir Zod aracını birlikte gösteriyor. OpenRouter Vercel AI SDK rehberi de aynı createOpenRouter() ve openrouter("provider/model") yaklaşımını kullanıyor.

import { createOpenRouter } from "@openrouter/ai-sdk-provider";
import { isStepCount, streamText, tool } from "ai";
import { z } from "zod";

const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const result = streamText({
  model: openrouter("openai/gpt-4o"),
  tools: {
    getWeather: tool({
      description: "Get the current weather in a location",
      inputSchema: z.object({
        location: z.string().describe("City and state"),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 18,
        unit: "celsius",
      }),
    }),
  },
  stopWhen: isStepCount(3),
  prompt: "What is the weather in San Francisco?",
});

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

textStream metin farklarını sunar. Uygulamanın reasoning, araç çağrıları, araç sonuçları, adım sınırları veya bitiş olaylarına ihtiyacı varsa fullStream kullanın; AI SDK streamText() referansı bu sonuç arayüzlerini belgeler. Yukarıdaki hava durumu çalıştırıcısı canlı bir API çağrısı değil, mock bir uygulamadır.

Herkese açık bir OpenRouter sağlayıcı issue’su, @openrouter/ai-sdk-provider 2.2.3, AI SDK 6.0.81, Node.js 24 ve openai/gpt-5.2 kullanılan çok parçalı bir araç çağrısı akışında algılanan buffering sorununu bildirdi. Rapora göre tool-input-end olayı eksikti. Bunu genel bir davranış değil, belirli bir sürüme özgü sorun olarak değerlendirin. Sorun sizde de tekrarlanırsa issue’da şu geçici çözüm öneriliyor:

import { createOpenAI } from "@ai-sdk/openai";

const openrouter = createOpenAI({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: "https://openrouter.ai/api/v1",
});

const model = openrouter.chat("openai/gpt-5.2");

@ai-sdk/openai paketini ayrıca yükleyin ve test ettiğiniz sürümleri sabitleyin. Bu çözüm sağlayıcı adaptörünü değiştirir; dolayısıyla OpenRouter’a özgü hangi seçeneklerin kullanılabilir olmaya devam ettiğini doğrulayın.

Anthropic Agent SDK + OpenRouter

Anthropic Agent SDK ayrı bir entegrasyon sınırıdır. OpenRouter’ın resmi Agent SDK rehberine göre SDK, çalışma zamanı olarak Claude Code’u kullanır ve şu ortam yapılandırmasını kabul eder:

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

ANTHROPIC_API_KEY değerinin boş bırakılması kasıtlıdır. OpenRouter anahtarı ANTHROPIC_AUTH_TOKEN içine yazılır. Bu Agent SDK kurulumunda /api yolunu OpenAI uyumlu /api/v1 yoluyla değiştirmeyin.

Rehberdeki TypeScript kullanımı şöyledir:

npm install @anthropic-ai/claude-agent-sdk

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and explain the bug in auth.py.",
  options: {
    allowedTools: ["Read"],
  },
})) {
  if (message.type === "assistant") {
    console.log(message.message.content);
  }
}

OpenRouter model endpoint’ini sağlar; ajan döngüsü ve araç çalışma zamanı ise Agent SDK’de kalır. Anthropic’e özgü özelliklerin birebir çalışacağı varsayılmamalıdır. Bu nedenle araçları, streaming’i, context davranışını ve modele özel seçenekleri doğrudan dağıtıma çıkaracağınız rota üzerinde test edin.

401, 404 ve “curl çalışıyor ama SDK çalışmıyor” sorunları

Model değiştirmeden önce hatanın hangi katmanda oluştuğunu belirleyin. Kimlik doğrulama, URL oluşturma, model bulma, sağlayıcı filtreleme ve parametre doğrulama farklı çözümler gerektirir.

OpenRouter, GET /api/v1/key endpoint’ini kimlik doğrulamalı API anahtarı kontrolü olarak belgeler. LangChain’de hata aramaya başlamadan önce bunu çalıştırın:

curl -sS https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Ardından model keşfini doğrulayın:

curl -sS https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Models API, araç destekleyen modelleri araç eklemeden önce filtrelemenize olanak tanır:

curl -sS \
  "https://openrouter.ai/api/v1/models?supported_parameters=tools" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

404 hatası, model mevcut olsa bile istek filtreleri sonrasında uygun sağlayıcı kalmadığı anlamına da gelebilir. Yönlendirme kararlarını incelemek için isteğe bağlı X-OpenRouter-Metadata: enabled header’ını etkinleştirin. Router Metadata dokümantasyonu, ortaya çıkan openrouter_metadata nesnesini ve hata davranışını açıklıyor.

Geliştirme sırasında anahtarı maskeleyerek oluşturulan isteği karşılaştırın: base URL, son yol, Authorization header’ının mevcut olup olmadığı, tam model ID’si ve sağlayıcıya özel gövde alanları. Kimlik doğrulamaya odaklanan devam rehberi için AIReiter’ın geçersiz API anahtarı ve 401/403 sorun giderme rehberine bakabilirsiniz.

Üretime geçiş için kontrol listesi

1. Paket sürümlerini aynı çizgide tutun. Eski bir eğitimdeki sürümleri kopyalamak yerine langchain, langchain-core ve langchain-openrouter veya @langchain/openrouter paketlerinin birbiriyle uyumlu olduğundan emin olun.
2. Kanonik model ID’lerini çözümleyin. /api/v1/models endpoint’ini veya OpenRouter model kataloğunu kullanın; alias’ları bilinçli bir davranış değişikliği olarak değerlendirin.
3. Fallback sınırını belirleyin. Sağlayıcı fallback’i erişilebilirliği artırır. Model fallback’i ise kaliteyi, gecikmeyi, yetenekleri ve maliyeti değiştirebilir. OpenRouter’ın döndürdüğü son model değerini kaydedin.
4. Gerekli yetenekleri zorunlu tutun. Araç ve yapılandırılmış çıktı isteklerinde sağlayıcı yetenek filtrelerini kullanın; araç desteğini katı JSON Schema desteğinin kanıtı olarak görmeyin.
5. Uygulama çıktılarınızı doğrulayın. Pydantic, Zod veya başka bir doğrulayıcı; araç argümanlarını ve yapılandırılmış yanıtları sonraki kod bunlarla işlem yapmadan önce kontrol etmelidir.
6. Faydalı metadata’yı log’layın. Gizlilik politikanız izin verdiği sürece request ID, model, kullanım bilgileri, bitiş nedeni ve hizmet veren sağlayıcı bilgisini saklayın. LangChain entegrasyonu ayrıca istekleri gruplamak için session_id ve istek başına metadata için trace kullanımını belgeler.
7. Her iki streaming modunu da test edin. Streaming olmadan başarılı olan bir çağrı, araç çağrısı parçalarının veya arayüz streaming’inin de doğru çalıştığını göstermez.
8. Sağlayıcı kısıtlarını deneyin. only, ignore, veri toplama filtreleri veya fiyat sınırı kullanıyorsanız uygun sağlayıcı bulunamadığında oluşan hata yolunu test edin.
9. Kimlik bilgilerini sunucu tarafında tutun. OPENROUTER_API_KEY değerini sunucu ortamında veya bir secret manager’da saklayın; tarayıcı paketine ya da commit edilmiş bir .env dosyasına koymayın.

En güvenilir sıra şudur: anahtarı doğrulayın, model ID’sini doğrulayın, önce düz metinle tek bir çağrı yapın; ardından yönlendirme, araçlar, yapılandırılmış çıktı ve çok adımlı streaming özelliklerini ekleyin.