Blog

Vercel AI SDK: Dein Anfänger-Guide zur Nutzung

Rebecca Kovács

Rebecca Kovács

10 June 2025

Vercel AI SDK: Dein Anfänger-Guide zur Nutzung

Willkommen zur definitiven Anfängeranleitung für das Vercel AI SDK. In einer Welt, in der künstliche Intelligenz die digitale Landschaft rasant verändert, hat sich die Fähigkeit, KI in Webanwendungen zu integrieren, von einer Nischenspezialisierung zu einer Kernkompetenz für moderne Entwickler entwickelt. Diese Anleitung wurde entwickelt, um Sie von einem neugierigen Anfänger zu einem fähigen Entwickler von KI-Anwendungen zu machen.

Lange Zeit war es ein komplexes Unterfangen, die Lücke zwischen einem leistungsstarken Large Language Model (LLM) und einer benutzerfreundlichen Weboberfläche zu schließen. Entwickler mussten sich mit unterschiedlichen Anbieter-APIs auseinandersetzen, komplizierten Zustand verwalten und Funktionen wie Response Streaming manuell implementieren. Das Vercel AI SDK wurde geschaffen, um genau diese Probleme zu lösen. Es ist ein TypeScript-basiertes Toolkit, das eine einheitliche, elegante Abstraktionsschicht über die Komplexität der Erstellung von KI-gestützten Erlebnissen bietet.

Dies ist nicht nur ein Schnellstart. Im Laufe dieses Tutorials werden wir einen vollständigen, funktionsreichen KI-Chatbot von Grund auf neu mit Next.js und Googles Gemini-Modell erstellen. Wir werden weit über ein einfaches "Hello World"-Beispiel hinausgehen. Sie werden lernen:

Am Ende dieser umfassenden Anleitung werden Sie nicht nur einen funktionierenden, fortschrittlichen Chatbot haben, sondern auch das tiefe konzeptionelle Wissen, das Sie benötigen, um selbstbewusst Ihre eigenen einzigartigen und leistungsstarken KI-gestützten Anwendungen mit dem Vercel AI SDK zu erstellen.

💡
Sie wünschen sich ein großartiges API-Testwerkzeug, das wunderschöne API-Dokumentationen generiert?

Sie wünschen sich eine integrierte All-in-One-Plattform, auf der Ihr Entwicklerteam mit maximaler Produktivität zusammenarbeiten kann?

Apidog erfüllt alle Ihre Anforderungen und ersetzt Postman zu einem viel günstigeren Preis!
button

Kapitel 1: Grundlagen und Einrichtung

Jedes großartige Bauwerk braucht ein solides Fundament. In diesem Kapitel richten wir unsere Entwicklungsumgebung ein, installieren die notwendigen Werkzeuge und bringen unsere API-Schlüssel in Ordnung. Wir werden uns auch einen Moment Zeit nehmen, um das "Warum" hinter jeder Entscheidung zu verstehen.

Voraussetzungen

Bevor wir eine einzige Codezeile schreiben, stellen wir sicher, dass Ihr Werkzeugkasten bereit ist.

  1. Navigieren Sie zu Google AI Studio.
  2. Melden Sie sich mit Ihrem Google-Konto an.
  3. Klicken Sie auf "Get API key" und dann auf "Create API key in new project".
  4. Kopieren Sie den generierten Schlüssel und speichern Sie ihn vorerst sicher ab. Behandeln Sie diesen Schlüssel wie ein Passwort; geben Sie ihn niemals öffentlich preis.

Schritt 1: Initialisieren des Next.js-Projekts

Wir werden Next.js verwenden, das führende React-Framework für die Erstellung produktionsreifer Anwendungen. Sein App Router-Paradigma integriert sich perfekt in die serverzentrierte Natur von KI-Anwendungen.

Öffnen Sie Ihr Terminal und führen Sie diesen Befehl aus, um ein neues Projekt zu erstellen:

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

Der Installer wird Ihnen mehrere Fragen stellen. Verwenden Sie diese Einstellungen, um nahtlos folgen zu können:

Sobald die Installation abgeschlossen ist, navigieren Sie in Ihr neu erstelltes Projektverzeichnis:

cd vercel-ai-tutorial

Schritt 2: Installieren des Vercel AI SDK

Fügen wir nun die AI SDK-Pakete zu unserem Projekt hinzu.

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

Lassen Sie uns aufschlüsseln, was jedes dieser Pakete tut:

Schritt 3: Sichern Ihres API-Schlüssels

Hardcodieren Sie niemals einen API-Schlüssel in Ihrem Anwendungscode. Dies ist ein großes Sicherheitsrisiko. Der professionelle Standard ist die Verwendung von Umgebungsvariablen. Next.js verfügt über eine integrierte Unterstützung dafür mit .env.local-Dateien.

Erstellen Sie die Datei im Stammverzeichnis Ihres Projekts:

touch .env.local

Öffnen Sie nun diese neue Datei und fügen Sie Ihren Google AI-Schlüssel hinzu:

# .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

Ersetzen Sie YOUR_GOOGLE_AI_API_KEY durch den Schlüssel, den Sie zuvor kopiert haben. Next.js lädt diese Datei automatisch und macht den Schlüssel auf dem Server verfügbar, genau dort, wo wir ihn brauchen.

Kapitel 2: Aufbau des Chatbot-Rückgrats

Nachdem unser Projekt eingerichtet ist, ist es an der Zeit, die Kernkomponenten unserer Anwendung zu erstellen: den serverseitigen API-Endpunkt, der mit der KI spricht, und die clientseitige Benutzeroberfläche, mit der Benutzer interagieren werden.

Die Client-Server-Architektur einer KI-App

Unser Chatbot wird aus zwei Hauptteilen bestehen:

  1. Eine serverseitige API-Route (/api/chat/route.ts): Dies ist eine sichere Umgebung, die auf einem Server läuft. Ihre Hauptaufgabe ist es, den Chatverlauf vom Browser des Benutzers zu empfangen, unseren geheimen API-Schlüssel hinzuzufügen, die Anfrage an den Google AI-Dienst weiterzuleiten und dann die Antwort zurück an den Benutzer zu streamen. Die Beibehaltung dieser Logik auf dem Server ist entscheidend für die Sicherheit – sie stellt sicher, dass unser API-Schlüssel niemals öffentlich zugänglich gemacht wird.
  2. Eine clientseitige Benutzeroberfläche (page.tsx): Dies ist die React-Komponente, die im Browser des Benutzers läuft. Sie ist verantwortlich für das Rendern des Chatverlaufs, das Erfassen der Benutzereingabe und das Senden dieser Eingabe an unsere API-Route.

Diese Trennung ist grundlegend für den Aufbau sicherer und leistungsfähiger Webanwendungen.

Schritt 4: Erstellen des API-Route-Handlers

Erstellen wir den serverseitigen Endpunkt. Erstellen Sie in Ihrem Verzeichnis src/app einen neuen Ordner api und darin einen weiteren Ordner chat. Erstellen Sie schließlich eine Datei namens route.ts im Ordner chat.

Der endgültige Pfad sollte src/app/api/chat/route.ts sein.

Füllen Sie diese Datei mit dem folgenden Code:

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

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

// Vercel-spezifische Konfiguration, um Streaming-Antworten für bis zu 30 Sekunden zu ermöglichen
export const maxDuration = 30;

// Der Haupt-API-Route-Handler
export async function POST(req: Request) {
  try {
    // Extrahieren Sie das `messages`-Array aus dem Anforderungsbody
    const { messages } = await req.json();

    // Rufen Sie den KI-Anbieter mit dem Konversationsverlauf auf
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // Das `messages`-Array liefert dem Modell Kontext für die Konversation
      messages,
    });

    // Antworten Sie mit einer Streaming-Antwort
    return result.toDataStreamResponse();
  } catch (error) {
    // Es ist eine gute Praxis, potenzielle Fehler zu behandeln
    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 });
  }
}

Lassen Sie uns diese entscheidende Datei analysieren:

Schritt 5: Erstellen der Benutzeroberfläche

Nun zum spaßigen Teil: dem Aufbau der Benutzeroberfläche. Dank des @ai-sdk/react-Pakets ist dies überraschend einfach. Öffnen Sie die Hauptseitendatei unter src/app/page.tsx und ersetzen Sie ihren gesamten Inhalt durch Folgendes:

// 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();

  // Eine Referenz auf den scrollbaren Container der Nachrichten
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Effekt zum Scrollen zum Ende des Nachrichtencontainers, wenn sich Nachrichten ändern
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Nachrichtencontainer */}
      <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'}`}
          >
            {/* Avatar des Benutzers anzeigen */}
            {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>
            )}

            {/* Nachrichtenblase */}
            <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' ? 'You' : 'AI Assistant'}</span>
              {m.content}
            </div>

            {/* Avatar der KI anzeigen */}
            {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>

      {/* Eingabeformular */}
      <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="Ask me anything..."
            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}
          >
            Send
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

Dies ist eine beträchtliche Menge an Code, aber der größte Teil davon dient der Erstellung einer ausgefeilten Benutzeroberfläche mit Tailwind CSS. Konzentrieren wir uns auf die Logik:

Schritt 6: Ausführen Ihrer Anwendung

Sie haben nun einen vollständigen, gut strukturierten KI-Chatbot erstellt. Starten wir ihn!

npm run dev

Navigieren Sie in Ihrem Browser zu http://localhost:3000. Sie sollten von einer ausgefeilten Chat-Oberfläche begrüßt werden. Stellen Sie eine Frage. Sie werden sehen, wie Ihre Nachricht sofort erscheint und die Antwort der KI Token für Token gestreamt wird.

Kapitel 3: Erweiterte Fähigkeiten - Verleihen Sie Ihrem Chatbot Superkräfte

Unser Chatbot ist intelligent, aber sein Wissen ist auf seine Trainingsdaten beschränkt. Er kann nicht auf Live-Informationen zugreifen oder Aktionen in der realen Welt ausführen. In diesem Kapitel werden wir ihm "Tools" geben, um diese Einschränkungen zu überwinden.

Was sind Tools?

Ein Tool ist eine Funktion, die Sie definieren und die das LLM ausführen kann. Sie beschreiben das Tool dem Modell, und wenn das Modell der Meinung ist, dass das Tool zur Beantwortung einer Benutzeranfrage notwendig ist, unterbricht es die Textgenerierung und gibt stattdessen ein spezielles "Tool Call"-Objekt aus. Ihr Code führt dann die Funktion mit den vom Modell bereitgestellten Argumenten aus, und das Ergebnis wird an das Modell zurückgesendet. Das Modell verwendet dann diese neuen Informationen, um seine endgültige, genauere Antwort zu generieren.

Geben wir unserem Chatbot zwei Tools:

  1. Ein Tool, um das aktuelle Wetter für einen Standort abzurufen.
  2. Ein Tool, um Temperaturen von Fahrenheit in Celsius umzurechnen.

Dadurch kann unser Bot Fragen wie "Wie ist das Wetter in London in Celsius?" beantworten – eine Aufgabe, die mehrere Schritte und externe Daten erfordert.

Schritt 7: Upgrade der API zur Unterstützung von Tools

Wir müssen unsere Tools im streamText-Aufruf auf dem Server definieren. Öffnen Sie src/app/api/chat/route.ts und ändern Sie es, um die neue tools-Definition aufzunehmen.

// 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,
    // Definieren Sie die Tools, die das Modell verwenden kann
    tools: {
      getWeather: tool({
        description: 'Get the current weather for a specific location. Always returns temperature in Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('The city and state, e.g., San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // In einer echten App würden Sie von einer echten Wetter-API abrufen
          console.log(`Fetching weather for ${location}`);
          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: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Convert a temperature from Fahrenheit to Celsius.',
        parameters: z.object({
          temperature: z.number().describe('The temperature in Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Converting ${temperature}°F to Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Analysieren wir das tools-Objekt:

Schritt 8: Aktivieren von mehrstufigen Tool Calls in der Benutzeroberfläche

Das alleinige Definieren der Tools auf dem Server reicht nicht aus. Standardmäßig stoppt die Konversation, wenn das Modell einen Tool Call durchführt. Wir müssen unserem useChat-Hook mitteilen, dass er das Ergebnis dieses Tool Calls automatisch an das Modell zurücksenden soll, damit es seine Argumentation fortsetzen und eine endgültige Antwort formulieren kann.

Dies ist unglaublich einfach. Aktualisieren Sie in src/app/page.tsx die Initialisierung des useChat-Hooks:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Sagen Sie dem Hook, dass er Tool-Ergebnisse automatisch an das Modell zurücksenden soll
    experimental_sendExtraToolMessages: true,
  });
  // ... Rest der Komponente
}

Das ist alles. Die Eigenschaft experimental_sendExtraToolMessages: true aktiviert den mehrstufigen Tool-Use-Flow.

Schritt 9: Eine bessere Benutzeroberfläche für Tool-Aufrufe

Unsere aktuelle Benutzeroberfläche zeigt nur m.content an. Wenn ein Tool aufgerufen wird, befinden sich die interessanten Informationen in einer anderen Eigenschaft des Nachrichtenobjekts. Erstellen wir eine dedizierte Komponente, um Tool Calls schön zu rendern.

Zuerst aktualisieren wir die Hauptnachrichtenschleife in src/app/page.tsx, um diese Aufrufe zu rendern.

// src/app/page.tsx

// ... innerhalb der return-Anweisung der Chat-Komponente
<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'}`}
    >
      {/* ... Avatare ... */}
      <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' ? 'You' : 'AI Assistant'}</span>

        {/* Tool-Aufrufe rendern */}
        {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">Tool Call: `{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>
      {/* ... Avatare ... */}
    </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>
// ...

Ich habe auch eine einfache Tippanzeige hinzugefügt, die erscheint, während der Assistent nachdenkt. Sie müssen dafür ein wenig CSS hinzufügen. Fügen Sie in Ihrer Datei src/app/globals.css Folgendes hinzu:

/* 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); }
}

Führen Sie nun die Anwendung erneut aus. Fragen Sie: "Wie ist das Wetter in New York in Celsius?". Sie werden eine faszinierende Kette von Ereignissen in Ihrer Benutzeroberfläche sehen:

  1. Das Modell wird zuerst das Tool getWeather aufrufen. Sie sehen den gerenderten Tool Call in der Benutzeroberfläche.
  2. Das Ergebnis (eine zufällige Temperatur in Fahrenheit) wird an das Modell zurückgesendet.
  3. Das Modell, das weiß, dass es Celsius benötigt, wird dann das Tool convertFahrenheitToCelsius aufrufen und dabei die Temperatur aus dem Ergebnis des ersten Tools als Eingabe verwenden.
  4. Schließlich, mit der Celsius-Temperatur in der Hand, generiert es eine natürlichsprachliche Antwort auf Ihre ursprüngliche Frage.

Dies ist die Kraft des Aufbaus von KI-Agenten, und das Vercel AI SDK macht diese komplexe Orchestrierung bemerkenswert einfach.

Kapitel 4: Wie geht es von hier aus weiter?

Sie haben erfolgreich einen fortschrittlichen, KI-gestützten Chatbot erstellt. Sie sind von einer leeren Leinwand zu einer funktionsreichen Anwendung gelangt, die Antworten streamen, Lade- und Fehlerzustände verarbeiten und Tools nutzen kann, um in einem mehrstufigen Prozess mit externen Daten zu interagieren.

Diese Anleitung hat Ihnen eine starke Grundlage gegeben, aber es ist nur der Anfang. Das Vercel AI SDK hat noch mehr zu bieten. Hier sind einige Wege für Ihre weitere Erkundung:

Die Zukunft der Webentwicklung ist intelligent, interaktiv und personalisiert. Mit dem Vercel AI SDK verfügen Sie nun über die Werkzeuge und das Wissen, um an vorderster Front dieser Revolution zu stehen. Viel Spaß beim Entwickeln!

💡
Sie wünschen sich ein großartiges API-Testwerkzeug, das wunderschöne API-Dokumentationen generiert?

Sie wünschen sich eine integrierte All-in-One-Plattform, auf der Ihr Entwicklerteam mit maximaler Produktivität zusammenarbeiten kann?

Apidog erfüllt alle Ihre Anforderungen und ersetzt Postman zu einem viel günstigeren Preis!
button

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload