1. Przedstawienie interfejsu API asystentów OpenAI

1.1 Definicja i Cel interfejsu API Asystentów

Interfejs API Asystentów umożliwia programistom budowanie sztucznych inteligentnych asystentów w ramach ich własnych aplikacji. Poprzez definiowanie niestandardowych poleceń i wybór modeli, asystenci mogą wykorzystywać modele, narzędzia i wiedzę do reagowania na zapytania użytkowników. Obecnie interfejs API Asystentów obsługuje trzy rodzaje narzędzi: Interpreter kodu, Przechwytywanie oraz Wywołanie funkcji.

1.2 Zastosowania interfejsu API Asystentów

Interfejs API Asystentów nadaje się do różnych scenariuszy, które wymagają interaktywnego wsparcia sztucznej inteligencji. Na przykład:

  • Obsługa klienta: Automatyczne udzielanie odpowiedzi na częste pytania, aby zmniejszyć obciążenie ludzkiej obsługi klienta.
  • Edukacja online: Odpowiadanie na pytania studentów i dostarczanie spersonalizowanego wsparcia edukacyjnego.
  • Analiza danych: Analizowanie plików danych przesłanych przez użytkowników, generowanie raportów i wizualizacja wykresów.
  • Spersonalizowane rekomendacje: Udzielanie spersonalizowanych sugestii i usług na podstawie historycznych interakcji użytkowników.

1.3 Podstawowe pojęcia Asystentów

Główne obiekty interfejsu API Asystentów obejmują Asystenta, Wątek i Wiadomość. Oto szczegółowe wprowadzenie do tych obiektów i ich funkcji:

Asystent

Obiekt Asystenta jest oparty na modelach OpenAI i może wywoływać narzędzia asystentów sztucznej inteligencji. Możesz dostosować instrukcje Asystenta, aby dopasować jego osobowość i funkcjonalność. Na przykład, możesz stworzyć Asystenta o nazwie "Analityk danych", który analizuje dane i generuje wykresy, korzystając z narzędzia "interpreter_kodu".

Wątek

Obiekt Wątku reprezentuje sesję rozmowy między użytkownikiem a Asystentem. Możesz utworzyć Wątek dla każdego użytkownika i dodawać do niego wiadomości, gdy użytkownik prowadzi interakcję z Asystentem. Obiekt Wątku przechowuje historię wiadomości i przycinanie wiadomości w celu spełnienia ograniczenia długości kontekstu modelu.

Wiadomość

Obiekt Wiadomości może być utworzony przez użytkownika lub Asystenta. Wiadomości mogą zawierać tekst, obrazy i inne pliki. Wiadomości są przechowywane jako lista w Wątku. W rzeczywistym użyciu interfejsu API, programiści mogą dodawać wiadomości użytkowników do Wątku i wywoływać odpowiedź Asystenta w razie potrzeby.

Wywołanie (Run)

Obiekt Run reprezentuje wykonanie żądania asystenta, wywołując asystenta na podstawie treści wiadomości w Wątku. Asystent wykorzystuje swoją konfigurację i wiadomości Wątku do wykonywania zadań poprzez wywoływanie modeli i narzędzi. W ramach wywołania, asystent dołącza wiadomości do wątku.

2. Proces Rozwoju interfejsu API Asystentów

2.1 Utwórz swojego Asystenta

Aby stworzyć Asystenta, musisz wysłać żądanie do interfejsu API z instrukcjami, nazwą modelu i konfiguracją narzędzi. Oto prosty przykład tworzenia osobistego asystenta do matematyki:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TWÓJ_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Jesteś osobistym nauczycielem matematyki. Napisz i uruchom kod, aby odpowiedzieć na pytania z matematyki.",
    "name": "Nauczyciel Matematyki",
    "tools": [{"type": "interpreter_kodu"}],
    "model": "gpt-4"
  }'

Parametry interfejsu API:

  • instructions - instrukcje systemowe mówiące asystentowi, co ma zrobić.
  • name - nazwa asystenta.
  • tools - definiuje, które narzędzia może użyć asystent. Każdy asystent może mieć maksymalnie 128 narzędzi. Obecne typy narzędzi to interpreter_kodu, przechwytywanie lub funkcja.
  • model - który model powinien używać asystent?

Po pomyślnym utworzeniu Asystenta, otrzymasz identyfikator Asystenta.

2.2 Utwórz Wątek Sesji

Wątek reprezentuje rozmowę, i zalecamy tworzenie oddzielnego Wątku sesji dla każdego użytkownika rozpoczynającego rozmowę. Możesz utworzyć Wątek w następujący sposób:

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

Po utworzeniu Wątku, otrzymasz identyfikator Wątku.

2.3 Dodawanie wiadomości do wątku

Możesz dodać wiadomości do określonego wątku, które zawierają tekst i opcjonalnie umożliwiają użytkownikom przesyłanie plików. Na przykład:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TWÓJ_KLUCZ_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Muszę rozwiązać to równanie `3x + 11 = 14`. Czy możesz mi pomóc?"
    }'

Parametry API:

  • thread_id - reprezentuje identyfikator wątku rozmowy, który można uzyskać podczas tworzenia wątku.

Treść żądania API to wiadomość użytkownika, zwykle reprezentująca pytanie użytkownika, podobnie jak struktura wiadomości modelu rozmowy.

2.4 Uruchomienie Asystenta w celu wygenerowania odpowiedzi

Aby asystent odpowiadał na wiadomości użytkownika, trzeba utworzyć uruchomienie (Run). Pozwala to asystentowi odczytać wątek i zdecydować, czy korzystać z narzędzi (jeśli są włączone), czy po prostu użyć modelu, aby najlepiej odpowiedzieć na zapytanie.

Uwaga: Do tego momentu asystent nie odpowiedział na pytanie użytkownika. Dopiero po wywołaniu API Run asystent odpowie na pytanie użytkownika.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer TWÓJ_KLUCZ_API_OPENAI" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "identyfikator_asystenta",
    "instructions": "Nadaj użytkownikowi imię i nazwisko Jane Doe. Użytkownik ma konto premium."
  }'

Parametry API:

  • thread_id - reprezentuje identyfikator wątku rozmowy, który można uzyskać podczas tworzenia wątku.
  • assistant_id - reprezentuje identyfikator asystenta, który można uzyskać podczas tworzenia asystenta.
  • instructions - instrukcje asystenta, które mogą zastąpić instrukcje ustawione podczas tworzenia asystenta.

Pomyślne żądanie API zwróci identyfikator uruchomienia (Run).

2.5 Sprawdzenie statusu działania asystenta

Po uruchomieniu zadania (Run) w Asystencie, wykonanie zadania odbywa się asynchronicznie. Oznacza to, że musimy regularnie sprawdzać status uruchomienia, aby określić, czy zostało ono ukończone. Aby sprawdzić status uruchomienia, można wykonać żądanie HTTP przy użyciu CURL. Poniżej znajduje się szczegółowe wprowadzenie do tego procesu.

Przykład żądania CURL:

curl https://api.openai.com/v1/threads/watek_abc123/runs/uruchomienie_abc123 \
  -H "Authorization: Bearer $KLUCZ_API_OPENAI" \
  -H "OpenAI-Beta: assistants=v1"

Wyjaśnienie parametrów API:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: To jest adres URL żądania API, gdzie thread_abc123 to unikalny identyfikator wątku (Thread), a run_abc123 to unikalny identyfikator uruchomienia (Run).

Przykład treści odpowiedzi API:

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

Wyjaśnienie parametrów odpowiedzi API:

  • id: Unikalny identyfikator uruchomienia (Run).
  • object: Wskazuje typ zwróconego obiektu, który tutaj jest thread.run.
  • status: Status uruchomienia (Run), możliwe wartości to: queued, in_progress, completed, requires_action, failed, itp.
  • created_at: Znacznik czasu utworzenia uruchomienia (Run).

2.6 Pobieranie wyników odpowiedzi asystenta

Po zakończeniu uruchomienia asystenta można odczytać wyniki odpowiedzi asystenta, sprawdzając wiadomości dodane do wątku (Thread). Poniżej znajduje się demonstracja, jak wykonać żądanie za pomocą CURL oraz szczegółowe wyjaśnienie parametrów API.

Wskazówka: Podobnie jak w rozmowie z Asystentem, gdy Asystent skończy przetwarzać zapytanie użytkownika, doda wiadomość do wątku rozmowy (Thread). Dlatego wystarczy zapytać o ostatnią wiadomość w wątku rozmowy (Thread), aby otrzymać odpowiedź asystenta.

Przykład żądania CURL:

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

Wyjaśnienie parametrów API:

  • https://api.openai.com/v1/threads/thread_abc123/messages: Adres URL żądania API, gdzie thread_abc123 jest unikalnym identyfikatorem wątku (Thread).
  • Tak samo jak nagłówki żądania używane do sprawdzenia statusu uruchomienia wcześniej, w tym informacje uwierzytelniające i informacje o wersji API.

Przykład wyników odpowiedzi Asystenta:

W tym przykładzie użytkownik zadał Asystentowi pytanie matematyczne, a Asystent dodał wiadomość odpowiedzi do Wątku po jego przetworzeniu.

Użytkownik: Muszę rozwiązać równanie `3x + 11 = 14`. Czy możesz mi pomóc?
Asystent: Oczywiście, Jane Doe. Aby rozwiązać równanie `(3x + 11 = 14)`, musisz izolować `(x)` po jednej stronie równania. Pozwól, że obliczę wartość `(x)` dla Ciebie.
Asystent: Rozwiązaniem równania `(3x + 11 = 14)` jest `(x = 1)`.

Po uzyskaniu wyników odpowiedzi od Asystenta, można je przedstawić użytkownikowi, aby pomóc im lepiej zrozumieć i wykorzystać usługi świadczone przez Asystenta.

3. Narzędzia: Wbudowane narzędzia dostarczane przez OpenAI

3.1 Narzędzie interpretera kodu

Narzędzie interpretera kodu pozwala Asystentowi API pisać i uruchamiać kod Pythona w środowisku wykonawczym piaskownicy. To narzędzie może obsługiwać różne formaty danych i plików oraz generować pliki z danymi i obrazami graficznymi. Interpreter kodu umożliwia Asystentowi iteracyjne uruchamianie kodu do rozwiązywania skomplikowanych problemów programistycznych i matematycznych. Gdy napisany przez Asystenta kod nie jest w stanie się uruchomić, może on iterować ten kod, próbując różnych kodów, aż kod zostanie pomyślnie uruchomiony.

Włączanie interpretera kodu

Aby włączyć interpretera kodu, należy przekazać code_interpreter w parametrze tools podczas tworzenia obiektu Asystenta:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Jesteś osobistym nauczycielem matematyki. Gdy zadane zostanie pytanie matematyczne, napisz i uruchom kod, aby na nie odpowiedzieć.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Następnie model podejmie decyzję o wywołaniu interpretera kodu podczas działania na podstawie charakteru żądania użytkownika. Możesz ułatwić to zachowanie poprzez instrukcje Asystenta (np. "Napisz kod, aby rozwiązać ten problem").

Użycie interpretera kodu do przetwarzania plików

Interpreter kodu może analizować dane z plików. Jest to przydatne, gdy chcesz dostarczyć duże ilości danych Asystentowi lub umożliwić użytkownikom przesyłanie własnych plików do analizy. Należy zauważyć, że pliki przesłane do interpretera kodu nie zostaną zindeksowane w celu odzyskania. Aby uzyskać szczegółowe informacje na temat indeksowania plików w celu odzyskania, należy odnieść się do sekcji Narzędzie odzyskiwania poniżej.

Pliki przekazane na poziomie Asystenta mogą być używane przez wszystkie uruchomienia powiązane z tym Asystentem:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/ścieżka/do/mojedane.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Jesteś osobistym nauczycielem matematyki. Gdy zadane zostanie pytanie matematyczne, napisz kod i uruchom go, aby na nie odpowiedzieć.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Odczytywanie obrazów i plików wygenerowanych przez interpreter kodu

Interpreter kodu może również generować pliki w API, takie jak wykresy obrazów, pliki CSV i pliki PDF. Istnieją dwa rodzaje wygenerowanych plików: obrazy i pliki danych (np. plik CSV z danymi wygenerowanymi przez asystenta).

Kiedy interpreter kodu generuje obraz, możesz znaleźć i pobrać ten plik w polu file_id odpowiedzi wiadomości asystenta:

{
    "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 Narzędzie do odzyskiwania

Narzędzie do odzyskiwania zwiększa możliwości asystenta poprzez dodawanie wiedzy spoza modelu (takiej jak informacje o własnych produktach lub dostarczone przez użytkownika dokumenty). Gdy plik jest przesłany i przekazany asystentowi, OpenAI automatycznie dzieli, indeksuje, przechowuje osadzenia Twojego dokumentu i stosuje wyszukiwanie wektorowe, aby odzyskać odpowiednie treści do odpowiedzi na zapytania użytkowników.

Włącz odzyskiwanie

Aby włączyć odzyskiwanie w parametrze tools asystenta, przekaż 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": "Jesteś czatem wsparcia klienta. Użyj swojej bazy wiedzy, aby skutecznie odpowiadać na zapytania klientów.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Prześlij pliki do odzyskiwania

Podobnie jak w przypadku Interpretera Kodu, pliki można przesyłać na poziomie asystenta lub na poziomie poszczególnych wiadomości.

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": "Jesteś czatem wsparcia klienta. Użyj swojej bazy wiedzy, aby skutecznie odpowiadać na zapytania klientów.",
    "name": "Korepetytor matematyczny",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Narzędzie do wywoływania funkcji

Podobnie jak w przypadku API Uzupełnień Czatu, API Asystentów obsługuje wywoływanie funkcji. Wywoływanie funkcji pozwala opisać funkcje asystentowi i inteligentnie zwrócić funkcję do wywołania wraz z jej parametrami. Gdy wywołane jest wywołanie funkcji, API Asystentów wstrzyma wykonanie, a Ty możesz podać wynik wywołania funkcji, aby kontynuować wykonanie.

Definiowanie funkcji

Podczas tworzenia Asystenta możesz zdefiniować zestaw funkcji, które asystent będzie wywoływał. Te funkcje muszą być jawnie określone podczas tworzenia obiektu asystenta. Każda funkcja powinna mieć unikalną nazwę, opis i specyfikację parametrów.

Poniższy kod przedstawia, jak zdefiniować dwie funkcje, korzystając z polecenia curl podczas tworzenia asystenta:

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": "Jesteś botem prognozy pogody. Użyj dostarczonych funkcji, aby odpowiadać na pytania.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Pobierz warunki pogodowe dla określonej lokalizacji",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Miasto i stan, np. San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Pobierz ksywkę dla miasta",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Miasto i stan, np. San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Odczytywanie wywołań funkcji przez Asystenta

Gdy użytkownik przesyła wiadomość do asystenta i treść wiadomości wywołuje funkcję, musisz odczytać informacje o tym wywołaniu funkcji. W tym procesie asystent wygeneruje działanie o statusie requires_action. W tym momencie możesz pobrać obiekt Run, aby uzyskać szczegółowe informacje o wywołaniu funkcji.

Oto przykład pobierania obiektu Run, pokazujący, jak uzyskać informacje o wywołaniach funkcji:

{
  "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\"}"
          }
        }
      ]
    }
  },
  ...
}

Parametr tool_calls zawiera informacje o wywołaniu funkcji, i wystarczy tylko wywołać odpowiednią funkcję w programie lokalnym.

Wysyłanie wyników funkcji

Po wykonaniu wywołania funkcji lokalnie i uzyskaniu wyników, musisz przesłać te wyniki do asystenta Assistants, aby asystent mógł kontynuować przetwarzanie żądania użytkownika. Podczas przesyłania wyników funkcji musisz upewnić się, że wyniki są skojarzone z pierwotnymi wywołaniami funkcji.

Oto przykładowy kod, jak przesłać wyniki wyjściowe funkcji:

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\"}"
      }
    ]
  }'

Wyjaśnienie parametrów:

  • thread_abc123 reprezentuje identyfikator wątku rozmowy
  • run_123 reprezentuje identyfikator obiektu Run
  • tool_call_id reprezentuje identyfikator konkretnego wywołania funkcji, który jest uzyskany z poprzedniego parametru tool_calls.

Po pomyślnym przesłaniu wszystkich wyników funkcji, stan obiektu Run zostanie ponownie zaktualizowany, a asystent będzie kontynuował przetwarzanie i zwróci ostateczną odpowiedź użytkownikowi.