1. Vorstellung der OpenAI Assistants API

1.1 Definition und Zweck der Assistants API

Die Assistants API ermöglicht es Entwicklern, künstliche Intelligenz-Assistenten innerhalb ihrer eigenen Anwendungen zu erstellen. Indem benutzerdefinierte Befehle definiert und Modelle ausgewählt werden, können Assistenten Modelle, Werkzeuge und Wissen nutzen, um auf Benutzeranfragen zu antworten. Aktuell unterstützt die Assistants API drei Arten von Werkzeugen: Code-Interpreter, Retrieval und Funktionsaufruf.

1.2 Anwendungen der Assistants API

Die Assistants API eignet sich für verschiedene Szenarien, die eine interaktive KI-Unterstützung erfordern. Zum Beispiel:

  • Kundenbetreuung: Beantworten Sie automatisch häufig gestellte Fragen, um die Arbeitsbelastung des menschlichen Kundenservice zu reduzieren.
  • Online-Bildung: Beantworten Sie Fragen von Studierenden und bieten Sie maßgeschneiderte Lernunterstützung.
  • Datenanalyse: Analysieren Sie von Benutzern hochgeladene Dateien, generieren Sie Berichte und visualisieren Sie Diagramme.
  • Personalisierte Empfehlungen: Bieten Sie personalisierte Vorschläge und Dienstleistungen basierend auf den historischen Interaktionen der Benutzer.

1.3 Kernkonzepte der Assistenten

Die Kernobjekte der Assistants API umfassen Assistant, Thread und Message. Hier sind detaillierte Einführungen zu diesen Objekten und ihren Funktionen:

Assistant

Das Assistant-Objekt basiert auf OpenAI-Modellen und kann die Werkzeuge von KI-Assistenten aufrufen. Sie können die Anweisungen des Assistenten anpassen, um seine Persönlichkeit und Funktionalität anzupassen. Zum Beispiel können Sie einen Assistenten namens "Datenanalyst" erstellen, der Daten analysiert und Diagramme mithilfe des "code_interpreter"-Werkzeugs generiert.

Thread

Das Thread-Objekt repräsentiert die Konversationssitzung zwischen dem Benutzer und dem Assistenten. Sie können für jeden Benutzer einen Thread erstellen und Nachrichten hinzufügen, wenn der Benutzer mit dem Assistenten interagiert. Das Thread-Objekt speichert effektiv den Verlauf von Nachrichten und kürzt Nachrichten bei Bedarf, um den Kontextlängenlimit des Modells einzuhalten.

Message

Das Message-Objekt kann vom Benutzer oder vom Assistenten erstellt werden. Nachrichten können Texte, Bilder und andere Dateien enthalten. Nachrichten werden als Liste im Thread gespeichert. Bei der tatsächlichen Verwendung der API können Entwickler Benutzernachrichten dem Thread hinzufügen und bei Bedarf die Antwort des Assistenten auslösen.

Run

Das Run-Objekt stellt die Ausführung einer Assistentenanfrage dar und ruft den Assistenten basierend auf dem Nachrichteninhalt im Thread auf. Der Assistent nutzt seine Konfiguration und die Nachrichten des Threads, um Aufgaben auszuführen, indem er Modelle und Werkzeuge aufruft. Im Rahmen des Ablaufs fügt der Assistent Nachrichten dem Thread hinzu.

2. Entwicklungsprozess der Assistants API

2.1 Erstellen Sie Ihren Assistenten

Um einen Assistenten zu erstellen, müssen Sie eine Anfrage an die API mit Anweisungen, Modellnamen und Werkzeugkonfiguration senden. Hier ist ein einfaches Beispiel zur Erstellung eines persönlichen Mathematik-Tutor-Assistenten:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer IHRE_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Du bist ein persönlicher Mathematik-Tutor. Schreibe und führe Code aus, um Mathematikfragen zu beantworten.",
    "name": "Mathematik-Tutor",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

API-Parameter:

  • instructions - Systemanweisungen, die dem Assistenten mitteilen, was zu tun ist.
  • name - der Name des Assistenten.
  • tools - definiert, welche Werkzeuge der Assistent verwenden kann. Jeder Assistent kann bis zu 128 Werkzeuge haben. Die aktuellen Werkzeugtypen können code_interpreter, retrieval oder function sein.
  • model - welches Modell soll der Assistent verwenden?

Nach erfolgreichem Erstellen des Assistenten erhalten Sie eine Assistenten-ID.

2.2 Erstellen Sie einen Session-Thread

Ein Thread repräsentiert eine Konversation, und es wird empfohlen, einen Sitzungsthread für jeden Benutzer zu erstellen, wenn sie eine Konversation starten. Sie können einen Thread wie folgt erstellen:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Nach dem Erstellen des Threads erhalten Sie eine Thread-ID.

2.3 Nachrichten zum Thread hinzufügen

Sie können Nachrichten zu einem bestimmten Thread hinzufügen, die Text enthalten und optional benutzeruploadbare Dateien zulassen. Zum Beispiel:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer DEIN_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Ich muss diese Gleichung lösen `3x + 11 = 14`. Kannst du mir helfen?"
    }'

API-Parameter:

  • thread_id - repräsentiert die Konversations-Thread-ID, die Sie beim Erstellen des Threads erhalten können.

Der API-Anforderungskörper ist eine Benutzernachricht, die normalerweise die Frage des Benutzers darstellt, ähnlich der Nachrichtenstruktur des Konversationsmodells.

2.4 Führen Sie den Assistenten aus, um eine Antwort zu generieren

Um den Assistenten auf Benutzernachrichten antworten zu lassen, müssen Sie einen Lauf erstellen. Dadurch kann der Assistent den Thread lesen und entscheiden, ob er Tools verwenden soll (falls aktiviert) oder einfach das Modell verwenden, um die Anfrage am besten zu beantworten.

Hinweis: Bis zu diesem Zeitpunkt hat der Assistent nicht auf die Frage des Benutzers geantwortet. Erst wenn Sie die Run-API aufrufen, wird der KI-Assistent auf die Frage des Benutzers antworten.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer DEIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "Sprechen Sie den Benutzer als Jane Doe an. Der Benutzer hat einen Premium-Account."
  }'

API-Parameter:

  • thread_id - repräsentiert die Konversations-Thread-ID, die Sie beim Erstellen des Threads erhalten können.
  • assistant_id - repräsentiert die Assistenten-ID, die Sie beim Erstellen des Assistenten erhalten können.
  • instructions - Assistentenanweisungen, die die beim Erstellen des Assistenten festgelegten Anweisungen außer Kraft setzen können.

Eine erfolgreiche API-Anfrage gibt eine Lauf-ID zurück.

2.5 Überprüfen des Assistentenstatus

Nachdem eine Aufgabe (Run) im Assistenten gestartet wurde, erfolgt die Aufgabenausführung asynchron. Dies bedeutet, dass wir regelmäßig den Status des Laufs überprüfen müssen, um festzustellen, ob er abgeschlossen ist. Um den Status des Laufs zu überprüfen, kann eine HTTP-Anfrage mit CURL durchgeführt werden. Nachfolgend wird dieser Vorgang spezifisch eingeführt.

Beispiel für CURL-Anforderung:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Erklärung der API-Parameter:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Dies ist die Anforderungs-URL der API, wobei thread_abc123 der eindeutige Bezeichner des Threads (Thread) und run_abc123 der eindeutige Bezeichner des Laufs ist.

Beispiel für den Antwortkörper:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Erklärung der API-Antwortparameter:

  • id: Der eindeutige Bezeichner des Laufs.
  • object: Gibt den Typ des zurückgegebenen Objekts an, der hier thread.run ist.
  • status: Der Status des Laufs, mögliche Werte sind queued, in_progress, completed, requires_action, failed usw.
  • created_at: Der Zeitstempel, wann der Lauf erstellt wurde.

2.6 Ergebnisse der Assistentenantwort abrufen

Nachdem der Assistentenlauf abgeschlossen ist, können wir die Antwortergebnisse des Assistenten lesen, indem wir die zum Thread hinzugefügten Nachrichten (Messages) überprüfen. Nachfolgend wird eine Demonstration beschrieben, wie die Anfrage über CURL gestellt wird, sowie eine ausführliche Erklärung der API-Parameter.

Tipp: Ähnlich wie bei einer Unterhaltung mit einem Assistenten fügt der Assistent, wenn er die Anfrage des Benutzers bearbeitet hat, eine Nachricht an den Konversations-Thread (Thread) an. Daher müssen wir nur die neueste Nachricht im Konversations-Thread (Thread) abfragen, um die Antwort des Assistenten zu erhalten.

Beispiel für CURL-Anforderung:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Erklärung der API-Parameter:

  • https://api.openai.com/v1/threads/thread_abc123/messages: Die Anforderungs-URL der API, wobei thread_abc123 der eindeutige Bezeichner des Threads (Thread) ist.
  • Gleich wie die Anforderungsheader, die zuvor zur Überprüfung des Ausführungsstatus verwendet wurden, einschließlich der Authentifizierungsinformationen und API-Version.

Beispiel für die Antwortergebnisse des Assistenten:

In diesem Beispiel stellte der Benutzer dem Assistenten eine mathematische Frage, und der Assistent fügte nach der Bearbeitung eine Antwortnachricht dem Thread hinzu.

Benutzer: Ich muss die Gleichung `3x + 11 = 14` lösen. Kannst du mir helfen?
Assistent: Natürlich, Jane Doe. Um die Gleichung `(3x + 11 = 14)` zu lösen, musst du `(x)` auf einer Seite der Gleichung isolieren. Lass mich den Wert von `(x)` für dich berechnen.
Assistent: Die Lösung der Gleichung `(3x + 11 = 14)` ist `(x = 1)`.

Nachdem der Assistent die Antwortergebnisse erhalten hat, können sie dem Benutzer präsentiert werden, um diesen dabei zu unterstützen, die von dem Assistenten bereitgestellten Dienste besser zu verstehen und zu nutzen.

3. Tools: Von OpenAI bereitgestellte integrierte Tools

3.1 Code Interpreter Tool

Das Code-Interpreter-Tool ermöglicht es dem Assistenten-API, Python-Code in einer Sandbox-Ausführungsumgebung zu schreiben und auszuführen. Dieses Tool kann verschiedene Daten- und Dateiformate verarbeiten und Dateien mit Daten und grafischen Bildern generieren. Der Code Interpreter ermöglicht es Ihrem Assistenten, iterativ Code auszuführen, um komplexe Codierungs- und mathematische Probleme zu lösen. Wenn der vom Assistenten geschriebene Code nicht erfolgreich ausgeführt wird, kann er diesen Code iterieren, indem er verschiedene Codes versucht, bis der Code erfolgreich ausgeführt wird.

Aktivieren des Code Interpreters

Um den Code Interpreter zu aktivieren, geben Sie beim Erstellen des Assistentenobjekts code_interpreter im tools-Parameter an:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Du bist ein persönlicher Mathe-Tutor. Schreibe und führe Code aus, um eine mathematische Frage zu beantworten.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Dann wird das Modell zur Laufzeit basierend auf der Art der Benutzeranfrage entscheiden, wann der Code Interpreter aufgerufen werden soll. Sie können dieses Verhalten durch die Anweisungen des Assistenten erleichtern (z. B. "Schreibe Code, um dieses Problem zu lösen").

Verwendung des Code Interpreters zur Verarbeitung von Dateien

Der Code Interpreter kann Daten aus Dateien parsen. Dies ist nützlich, wenn Sie dem Assistenten eine große Menge an Daten zur Verfügung stellen oder es Ihren Benutzern ermöglichen möchten, ihre eigenen Dateien für die Analyse hochzuladen. Beachten Sie, dass für den Code Interpreter hochgeladene Dateien nicht indiziert werden. Für detaillierte Informationen zur Indizierung von Dateien zur Wiederauffindung siehe den Abschnitt zum Retrieval Tool unten.

Für alle mit diesem Assistenten verknüpften Ausführungen kann auf auf Assistentenebene übergebene Dateien zugegriffen werden:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Du bist ein persönlicher Mathe-Tutor. Schreibe und führe Code aus, um eine mathematische Frage zu beantworten.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Lesen von Bildern und Dateien, die vom Code-Interpreter generiert wurden

Der Code-Interpreter kann auch Dateien in der API ausgeben, wie z.B. die Erstellung von Bildgrafiken, CSV- und PDF-Dateien. Es gibt zwei Arten von generierten Dateien: Bilder und Datendateien (z.B. eine CSV-Datei mit Daten, die vom Assistenten generiert wurden).

Wenn der Code-Interpreter ein Bild erzeugt, kannst du diese Datei im file_id-Feld der Antwort des Assistenten finden und herunterladen:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Abrufwerkzeug

Das Abrufwerkzeug erweitert die Fähigkeiten des Assistenten, indem es Wissen von außerhalb des Modells hinzufügt (wie proprietäre Produktinformationen oder vom Benutzer bereitgestellte Dokumente). Sobald die Datei hochgeladen und an den Assistenten übergeben wurde, wird OpenAI automatisch Ihre Dokumente zerschneiden, indizieren, Einbettungen speichern und Vektor-Suche implementieren, um relevante Inhalte zur Beantwortung von Benutzeranfragen abzurufen.

Abruf aktivieren

Um den Abruf im tools-Parameter des Assistenten zu aktivieren, übergeben Sie retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Du bist ein Chatbot für den Kundensupport. Verwende deine Wissensdatenbank, um effektiv auf Kundenanfragen zu antworten.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Dateien für den Abruf hochladen

Ähnlich wie beim Code-Interpreter können Dateien auf Assistentenebene oder auf individueller Nachrichtenebene hochgeladen werden.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Du bist ein Chatbot für den Kundensupport. Verwende deine Wissensdatenbank, um effektiv auf Kundenanfragen zu antworten.",
    "name": "Mathematik-Nachhilfe",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Funktionsaufrufwerkzeug

Ähnlich wie die Chat-Vervollständigungs-API unterstützt die Assistenten-API auch Funktionsaufrufe. Der Funktionsaufruf ermöglicht es, Funktionen zu beschreiben, die an den Assistenten übergeben und intelligent die auszuführende Funktion zusammen mit ihren Parametern zurückzugeben. Wenn ein Funktionsaufruf ausgeführt wird, wird die Ausführung des Assistenten-APIs pausiert, und Sie können das Ergebnis des Funktionsaufrufs bereitstellen, um die Ausführung fortzusetzen.

Funktionen definieren

Bei der Erstellung eines Assistenten können Sie eine Reihe von Funktionen definieren, die der Assistent aufrufen soll. Diese Funktionen müssen explizit angegeben werden, wenn das Assistentenobjekt erstellt wird. Jede Funktion sollte einen eindeutigen Namen, eine Beschreibung und eine Parameterangabe haben.

Der folgende Code zeigt, wie man zwei Funktionen definiert, die den curl-Befehl verwenden, um einen Assistenten zu erstellen:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Du bist ein Wettervorhersage-Bot. Verwende die bereitgestellten Funktionen, um Fragen zu beantworten.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Die Wetterbedingungen für einen bestimmten Ort abrufen",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Stadt und Staat, z.B. San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Den Spitznamen für eine Stadt abrufen",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Stadt und Staat, z.B. San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Aufrufen von Funktionen durch den Assistenten

Wenn ein Benutzer eine Nachricht an den Assistenten sendet und der Inhalt der Nachricht einen Funktionsaufruf auslöst, müssen Sie die Informationen dieses Funktionsaufrufs lesen. Während dieses Prozesses wird der Assistent einen Lauf mit dem Status erfordert_Aktion generieren. Zu diesem Zeitpunkt können Sie das Run-Objekt abrufen, um detaillierte Informationen über den Funktionsaufruf zu erhalten.

Das folgende Beispiel zeigt, wie man das Run-Objekt abruft und die Informationen der Funktionsaufrufe erhält:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

Der Parameter tool_calls enthält die Informationen zum Funktionsaufruf, und Sie müssen einfach die entsprechende Funktion in Ihrem lokalen Programm aufrufen.

Ergebnisse der Funktionsausführung übermitteln

Nachdem Sie den Funktionsaufruf lokal ausgeführt und die Ergebnisse erhalten haben, müssen Sie diese Ergebnisse an den Assistants-Assistenten übermitteln, damit der Assistent die Anfrage des Benutzers fortsetzen kann. Beim Übermitteln von Funktionsausgaben müssen Sie sicherstellen, dass die Ausgaben mit den ursprünglichen Funktionsaufrufen verknüpft sind.

Im Folgenden finden Sie ein Beispiel für die Übermittlung von Funktionsausgabenergebnissen:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Parametererklärung:

  • thread_abc123 repräsentiert die ID des Konversationsthreads
  • run_123 repräsentiert die ID des Run-Objekts
  • tool_call_id repräsentiert die ID eines bestimmten Funktionsaufrufs, die aus dem vorherigen tool_calls-Parameter stammt.

Nach erfolgreichem Übermitteln aller Funktionsausgaben wird der Status des Run-Objekts erneut aktualisiert, und der Assistent wird mit der Verarbeitung fortsetzen und die endgültige Antwort an den Benutzer zurückgeben.