Blog

Vercel AI SDK Kullanımı: Başlangıç Rehberi

Rebecca Kovács

Rebecca Kovács

10 June 2025

Vercel AI SDK Kullanımı: Başlangıç Rehberi

Vercel AI SDK'ya yönelik kesin başlangıç kılavuzuna hoş geldiniz. Yapay zekanın dijital ortamı hızla dönüştürdüğü bir dünyada, yapay zekayı web uygulamalarına entegre etme yeteneği, niş bir uzmanlıktan modern geliştiriciler için temel bir yetkinliğe dönüşmüştür. Bu kılavuz, sizi meraklı bir başlangıç seviyesinden yetenekli bir yapay zeka uygulama geliştiricisine taşımak için tasarlanmıştır.

Uzun bir süre boyunca, güçlü bir Büyük Dil Modeli (LLM) ile kullanıcı dostu bir web arayüzü arasındaki boşluğu kapatmak karmaşık bir çabaydı. Geliştiriciler, farklı sağlayıcı API'leriyle uğraşmak, karmaşık durumu yönetmek ve yanıt akışı gibi özellikleri manuel olarak uygulamak zorunda kalıyorlardı. Vercel AI SDK, tam olarak bu sorunları çözmek için oluşturuldu. Yapay zeka destekli deneyimler oluşturmanın karmaşıklıkları üzerinde birleşik, zarif bir soyutlama katmanı sağlayan, TypeScript öncelikli bir araç setidir.

Bu sadece bir hızlı başlangıç değildir. Bu eğitim boyunca, Next.js ve Google'ın Gemini modelini kullanarak sıfırdan eksiksiz, zengin özelliklere sahip bir yapay zeka sohbet robotu oluşturacağız. Basit bir "merhaba dünya" örneğinin çok ötesine geçeceğiz. Şunları öğreneceksiniz:

Bu kapsamlı kılavuzun sonunda, yalnızca çalışan, gelişmiş bir sohbet robotuna değil, aynı zamanda Vercel AI SDK ile kendi benzersiz ve güçlü yapay zeka destekli uygulamalarınızı güvenle oluşturmak için gereken derin kavramsal bilgiye de sahip olacaksınız.

💡
Oluşturan harika bir API Test aracına mı ihtiyacınız var güzel API Belgeleri?

Geliştirici Ekibinizin birlikte çalışması için entegre, Hepsi Bir Arada bir platforma mı ihtiyacınız var? maksimum üretkenlik?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

Bölüm 1: Temeller ve Kurulum

Her harika yapının sağlam bir temele ihtiyacı vardır. Bu bölümde, geliştirme ortamımızı kuracağız, gerekli araçları yükleyeceğiz ve API anahtarlarımızı düzenleyeceğiz. Ayrıca yaptığımız her seçimin arkasındaki "neden"i anlamak için bir an ayıracağız.

Ön Koşullar

Tek bir kod satırı yazmadan önce, araç kutunuzun hazır olduğundan emin olalım.

  1. Google AI Studio'ya gidin.
  2. Google hesabınızla oturum açın.
  3. "Get API key" (API anahtarını al) ve ardından "Create API key in new project" (Yeni projede API anahtarı oluştur) düğmesine tıklayın.
  4. Oluşturulan anahtarı kopyalayın ve şimdilik güvenli bir yere kaydedin. Bu anahtara bir parola gibi davranın; asla halka açık hale getirmeyin.

Adım 1: Next.js Projesini Başlatma

Üretim kalitesinde uygulamalar oluşturmak için önde gelen React çerçevesi olan Next.js'i kullanacağız. App Router paradigması, yapay zeka uygulamalarının sunucu merkezli doğasıyla mükemmel bir şekilde bütünleşir.

Terminalinizi açın ve yeni bir proje oluşturmak için şu komutu çalıştırın:

npx create-next-app@latest vercel-ai-tutorial

Yükleyici size birkaç soru soracaktır. Sorunsuz bir şekilde takip etmek için şu ayarları kullanın:

Kurulum tamamlandıktan sonra, yeni oluşturduğunuz proje dizinine gidin:

cd vercel-ai-tutorial

Adım 2: Vercel AI SDK'yı Yükleme

Şimdi, AI SDK paketlerini projemize ekleyelim.

npm install ai @ai-sdk/react @ai-sdk/google zod

Bu paketlerin her birinin ne işe yaradığını inceleyelim:

Adım 3: API Anahtarınızı Güvenli Hale Getirme

API anahtarını uygulamanızın kodunda asla sabit kodlamayın. Bu büyük bir güvenlik riskidir. Profesyonel standart, ortam değişkenlerini kullanmaktır. Next.js, .env.local dosyalarıyla bunun için yerleşik desteğe sahiptir.

Dosyayı projenizin kökünde oluşturun:

touch .env.local

Şimdi, bu yeni dosyayı açın ve Google AI anahtarınızı ekleyin:

# .env.local
# This file is for local development and should NOT be committed to git.
GOOGLE_GENERATIVE_AI_API_KEY=YOUR_GOOGLE_AI_API_KEY

YOUR_GOOGLE_AI_API_KEY yerine daha önce kopyaladığınız anahtarı yapıştırın. Next.js bu dosyayı otomatik olarak yükler ve anahtarı sunucuda kullanılabilir hale getirir, ki bu da tam olarak ihtiyacımız olan yerdir.

Bölüm 2: Sohbet Robotunun Omurgasını Oluşturma

Projemiz kurulduktan sonra, uygulamamızın çekirdek bileşenlerini oluşturmanın zamanı geldi: Yapay zeka ile konuşan sunucu tarafı API uç noktası ve kullanıcıların etkileşimde bulunacağı istemci tarafı kullanıcı arayüzü.

Bir Yapay Zeka Uygulamasının İstemci-Sunucu Mimarisi

Sohbet robotumuzun iki ana bölümü olacaktır:

  1. Bir Sunucu Tarafı API Rotası (/api/chat/route.ts): Bu, bir sunucuda çalışan güvenli bir ortamdır. Birincil görevi, kullanıcının tarayıcısından sohbet geçmişini almak, gizli API anahtarımızı eklemek, isteği Google AI hizmetine iletmek ve ardından yanıtı kullanıcıya geri akışla göndermektir. Bu mantığı sunucuda tutmak güvenlik açısından kritiktir; API anahtarımızın halka açık olmamasını sağlar.
  2. Bir İstemci Tarafı Kullanıcı Arayüzü (page.tsx): Bu, kullanıcının tarayıcısında çalışan React bileşenidir. Sohbet geçmişini oluşturmaktan, kullanıcı girişini yakalamaktan ve bu girişi API rotamıza göndermekten sorumludur.

Bu ayrım, güvenli ve yüksek performanslı web uygulamaları oluşturmak için temeldir.

Adım 4: API Rota İşleyicisini Oluşturma

Sunucu tarafı uç noktasını oluşturalım. src/app dizininizde, yeni bir klasör api oluşturun ve bunun içinde başka bir klasör chat oluşturun. Son olarak, chat klasörünün içine route.ts adlı bir dosya oluşturun.

Son yol src/app/api/chat/route.ts olmalıdır.

Bu dosyayı aşağıdaki kodla doldurun:

// src/app/api/chat/route.ts

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

// Yanıt akışına 30 saniyeye kadar izin veren Vercel'e özgü yapılandırma
export const maxDuration = 30;

// Ana API rota işleyicisi
export async function POST(req: Request) {
  try {
    // İstek gövdesinden `messages` dizisini çıkarın
    const { messages } = await req.json();

    // Sohbet geçmişiyle AI sağlayıcısını çağırın
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // `messages` dizisi, modele sohbet için bağlam sağlar
      messages,
    });

    // Akış yanıtıyla yanıt verin
    return result.toDataStreamResponse();
  } catch (error) {
    // Potansiyel hataları ele almak iyi bir uygulamadır
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'An unknown error occurred' }), { status: 500 });
  }
}

Bu önemli dosyayı inceleyelim:

Adım 5: Kullanıcı Arayüzünü Hazırlama

Şimdi eğlenceli kısım: Kullanıcı arayüzünü oluşturmak. @ai-sdk/react paketi sayesinde bu şaşırtıcı derecede basit. Ana sayfa dosyasını src/app/page.tsx adresinde açın ve tüm içeriğini aşağıdakilerle değiştirin:

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // Mesajların kaydırılabilir kapsayıcısına bir ref
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Mesajlar her değiştiğinde mesajlar kapsayıcısının altına kaydırma efekti
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Mesajlar kapsayıcısı */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* Kullanıcı avatarını göster */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* Mesaj balonu */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'Siz' : 'Yapay Zeka Asistanı'}</span>
              {m.content}
            </div>

            {/* Yapay Zeka avatarını göster */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
            )}
          </div>
        ))}
      </div>

      {/* Giriş formu */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Bana bir şey sor..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Gönder
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

Bu önemli miktarda kod, ancak çoğu Tailwind CSS ile gösterişli bir kullanıcı arayüzü oluşturmak için. Mantığa odaklanalım:

Adım 6: Uygulamanızı Çalıştırma

Artık eksiksiz, iyi yapılandırılmış bir yapay zeka sohbet robotu oluşturdunuz. Hadi başlatalım!

npm run dev

Tarayıcınızda http://localhost:3000 adresine gidin. Gösterişli bir sohbet arayüzü ile karşılaşmalısınız. Ona bir soru sorun. Mesajınızın anında göründüğünü ve yapay zekanın yanıtının token token akış halinde geldiğini göreceksiniz.

Bölüm 3: Gelişmiş Yetenekler - Sohbet Robotunuza Süper Güçler Verme

Sohbet robotumuz akıllı, ancak bilgisi eğitim verileriyle sınırlı. Canlı bilgilere erişemez veya gerçek dünyada eylemler gerçekleştiremez. Bu bölümde, bu sınırlamaların üstesinden gelmek için ona "Araçlar" vereceğiz.

Araçlar Nedir?

Bir Araç, LLM'nin yürütmeyi seçebileceği tanımladığınız bir fonksiyondur. Aracı modele tanımlarsınız ve model bir kullanıcının sorgusunu yanıtlamak için aracın gerekli olduğunu düşündüğünde, metin oluşturmayı duraklatır ve bunun yerine özel bir "araç çağrısı" nesnesi çıktısı verir. Kodunuz daha sonra model tarafından sağlanan argümanlarla fonksiyonu yürütür ve sonuç modele geri gönderilir. Model daha sonra bu yeni bilgiyi kullanarak son, daha doğru yanıtını oluşturur.

Sohbet robotumuzu iki araçla güçlendirelim:

  1. Bir konum için mevcut hava durumunu almak için bir araç.
  2. Sıcaklıkları Fahrenheit'tan Celsius'a dönüştürmek için bir araç.

Bu, botumuzun "Londra'da hava durumu Celsius cinsinden nedir?" gibi soruları yanıtlamasına olanak tanıyacaktır - bu, birden fazla adım ve harici veri gerektiren bir görevdir.

Adım 7: Araçları Desteklemek İçin API'yi Yükseltme

Sunucudaki streamText çağrısında araçlarımızı tanımlamamız gerekiyor. src/app/api/chat/route.ts dosyasını açın ve yeni tools tanımını içerecek şekilde değiştirin.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

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

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // Modelin kullanabileceği araçları tanımlayın
    tools: {
      getWeather: tool({
        description: 'Belirli bir konum için mevcut hava durumunu alın. Her zaman sıcaklığı Fahrenheit olarak döndürür.',
        parameters: z.object({
          location: z.string().describe('Şehir ve eyalet, örn: San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // Gerçek bir uygulamada, gerçek bir hava durumu API'sinden veri alırdınız
          console.log(`${location} için hava durumu getiriliyor`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Güneşli', 'Bulutlu', 'Yağmurlu'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Bir sıcaklığı Fahrenheit\'tan Celsius\'a dönüştürün.',
        parameters: z.object({
          temperature: z.number().describe('Fahrenheit cinsinden sıcaklık'),
        }),
        execute: async ({ temperature }) => {
          console.log(`${temperature}°F Celsius'a dönüştürülüyor`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

tools nesnesini analiz edelim:

Adım 8: Kullanıcı Arayüzünde Çok Adımlı Araç Çağrılarını Etkinleştirme

Araçları sadece sunucuda tanımlamak yeterli değildir. Varsayılan olarak, model bir araç çağrısı yaptığında, konuşma durur. useChat hook'umuza, o araç çağrısının sonucunu otomatik olarak modele geri göndermesini söylememiz gerekir, böylece akıl yürütmesine devam edebilir ve nihai bir yanıt formüle edebilir.

Bu inanılmaz derecede basittir. src/app/page.tsx dosyasında, useChat hook başlatmasını güncelleyin:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Hook'a araç sonuçlarını otomatik olarak modele geri göndermesini söyleyin
    experimental_sendExtraToolMessages: true,
  });
  // ... bileşenin geri kalanı
}

İşte bu kadar. experimental_sendExtraToolMessages: true özelliği, çok adımlı araç kullanım akışını etkinleştirir.

Adım 9: Araç Çağrıları İçin Daha İyi Bir Kullanıcı Arayüzü

Mevcut kullanıcı arayüzümüz yalnızca m.content'i görüntüler. Bir araç çağrıldığında, ilginç bilgi mesaj nesnesindeki farklı bir özellikte bulunur. Araç çağrılarını güzelce oluşturmak için özel bir bileşen oluşturalım.

Öncelikle, bu çağrıları oluşturmak için src/app/page.tsx dosyasındaki ana mesaj döngüsünü güncelleyelim.

// src/app/page.tsx

// ... Chat bileşeninin return ifadesinin içinde
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... avatarlar ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'Siz' : 'Yapay Zeka Asistanı'}</span>

        {/* Araç çağrılarını oluştur */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Araç Çağrısı: `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... avatarlar ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

Ayrıca, asistan düşünürken görünen basit bir yazma göstergesi de ekledim. Bunun için biraz CSS eklemeniz gerekecek. src/app/globals.css dosyanıza şunları ekleyin:

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

Şimdi, uygulamayı tekrar çalıştırın. Ona "New York'ta hava durumu Celsius cinsinden nedir?" diye sorun. Kullanıcı arayüzünüzde büyüleyici bir olay zincirinin ortaya çıktığını göreceksiniz:

  1. Model önce getWeather aracını çağıracaktır. Kullanıcı arayüzünde oluşturulan araç çağrısını göreceksiniz.
  2. Sonuç (Fahrenheit cinsinden rastgele bir sıcaklık) modele geri gönderilir.
  3. Model, Celsius'a ihtiyacı olduğunu bilerek, ilk aracın sonucundan gelen sıcaklığı girdi olarak kullanarak convertFahrenheitToCelsius aracını çağıracaktır.
  4. Son olarak, Celsius sıcaklığı elinde olduğunda, orijinal sorunuzu yanıtlayan doğal dilde bir yanıt oluşturacaktır.

Bu, Yapay Zeka Ajanları oluşturmanın gücüdür ve Vercel AI SDK, bu karmaşık düzenlemeyi dikkat çekici derecede basit hale getirir.

Bölüm 4: Buradan Nereye Gidilir?

Başarılı bir şekilde gelişmiş, yapay zeka destekli bir sohbet robotu oluşturdunuz. Boş bir tuvalden, yanıtları akış halinde gönderebilen, yükleme ve hata durumlarını yönetebilen ve harici verilerle çok adımlı bir şekilde etkileşim kurmak için araçlardan yararlanabilen zengin özelliklere sahip bir uygulamaya ulaştınız.

Bu kılavuz size güçlü bir temel sağladı, ancak bu sadece başlangıç. Vercel AI SDK'nın sunabileceği daha fazlası var. Sürekli keşifleriniz için bazı yollar şunlardır:

Web geliştirmenin geleceği akıllı, etkileşimli ve kişiselleştirilmiş. Vercel AI SDK ile artık bu devrimin ön saflarında yer almak için araçlara ve bilgiye sahipsiniz. İyi geliştirmeler!

💡
Oluşturan harika bir API Test aracına mı ihtiyacınız var güzel API Belgeleri?

Geliştirici Ekibinizin birlikte çalışması için entegre, Hepsi Bir Arada bir platforma mı ihtiyacınız var? maksimum üretkenlik?

Apidog tüm taleplerinizi karşılar ve Postman'ı çok daha uygun bir fiyata değiştirir!
button

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir