Udostępnij za pośrednictwem

Dokumentacja interfejsu API asystentów (wersja zapoznawcza)

  • Artykuł

Uwaga

  • Wyszukiwanie plików może pozyskiwać maksymalnie 10 000 plików na asystenta — 500 razy więcej niż wcześniej. Jest szybkie, obsługuje zapytania równoległe za pośrednictwem wyszukiwania wielowątkowego i oferuje ulepszone ponowne klasyfikowanie praz ponowne zapisywanie zapytań.
    • Magazyn wektorów to nowy obiekt w interfejsie API. Po dodaniu pliku do magazynu wektorów jest on automatycznie analizowany, fragmentowany i osadzany oraz przygotowywany do wyszukiwania. Magazyny wektorów mogą być używane między asystentami i wątkami, upraszczając zarządzanie plikami i rozliczenia.
  • Dodaliśmy obsługę parametru tool_choice , który może służyć do wymuszenia użycia określonego narzędzia (takiego jak wyszukiwanie plików, interpreter kodu lub funkcja) w określonym uruchomieniu.

Ten artykuł zawiera dokumentację referencyjną dla języka Python i interfejsu API REST dla nowego interfejsu API Asystentów (wersja zapoznawcza). Więcej szczegółowych wskazówek krok po kroku znajduje się w przewodniku wprowadzającym.

Tworzenie asystenta

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Utwórz asystenta przy użyciu modelu i instrukcji.

Treść żądania

Nazwisko Type Wymagania opis
model string Wymagania Nazwa wdrożenia modelu do użycia.
name ciąg lub wartość null Opcjonalnie Nazwa asystenta. Maksymalna długość to 256 znaków.
opis ciąg lub wartość null Opcjonalnie Opis asystenta. Maksymalna długość to 512 znaków.
instrukcje ciąg lub wartość null Opcjonalnie Instrukcje systemowe używane przez asystenta. Maksymalna długość to 256 000 znaków.
tools tablica Opcjonalnie Wartości domyślne to []. Lista narzędzi włączonych w asystencie. Może istnieć maksymalnie 128 narzędzi na asystenta. Narzędzia mogą być obecnie typami code_interpreter, lub function. function Opis może mieć maksymalnie 1024 znaki.
metadane map Opcjonalnie Zestaw 16 par klucz-wartość, które można dołączyć do obiektu. Może to być przydatne do przechowywania dodatkowych informacji o obiekcie w formacie ustrukturyzowanym. Klucze mogą mieć długość maksymalnie 64 znaków, a wartości mogą mieć długość maksymalnie 512 znaków.
temperature liczba lub wartość null Opcjonalnie Wartość domyślna to 1. Określa temperaturę próbkowania do użycia z zakresu od 0 do 2. Wyższe wartości, takie jak 0,8, sprawią, że dane wyjściowe będą bardziej losowe, a niższe wartości, takie jak 0,2, sprawią, że będzie bardziej skoncentrowany i deterministyczny.
top_p liczba lub wartość null Opcjonalnie Wartość domyślna to 1. Alternatywą dla próbkowania z temperaturą, nazywaną próbkowaniem jądra, gdzie model uwzględnia wyniki tokenów z top_p masą prawdopodobieństwa. Dlatego 0,1 oznacza, że uwzględniane są tylko tokeny składające się z pierwszej masy prawdopodobieństwa o 10%. Ogólnie zalecamy zmianę tej wartości lub temperatury, ale nie obu.
response_format ciąg lub obiekt Opcjonalnie Określa format, który model musi wyświetlić. Zgodny z GPT-4 Turbo i wszystkimi modelami GPT-3.5 Turbo od gpt-3.5-turbo-1106. Ustawienie tego parametru w celu { "type": "json_object" } włączenia trybu JSON, co gwarantuje, że komunikat generowany przez model jest prawidłowym kodem JSON. Co ważne, w przypadku korzystania z trybu JSON należy również poinstruować model, aby samodzielnie wygenerował kod JSON przy użyciu komunikatu systemowego lub użytkownika. Bez tej instrukcji model może wygenerować niekończący się strumień białych znaków, dopóki generowanie nie osiągnie limitu tokenu, co skutkuje długotrwałym i pozornie "zablokowanym" żądaniem. Ponadto zawartość wiadomości może zostać częściowo odcięta w przypadku użycia finish_reason="length"elementu , co oznacza przekroczenie max_tokens generacji lub przekroczenie maksymalnej długości kontekstu konwersacji.
tool_resources obiekt Opcjonalnie Zestaw zasobów używanych przez narzędzia asystenta. Zasoby są specyficzne dla typu narzędzia. Na przykład code_interpreter narzędzie wymaga listy identyfikatorów plików, a file_search narzędzie wymaga listy identyfikatorów magazynów wektorów.

Zwraca

Obiekt asystenta.

Przykładowe żądanie asystenta tworzenia

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

Asystentzy listy

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Zwraca listę wszystkich asystentów.

Parametry zapytań

Parametr Type Wymagania opis
limit integer Opcjonalnie Limit liczby zwracanych obiektów. Limit może mieścić się w zakresie od 1 do 100, a wartość domyślna to 20.
order string Opcjonalne — wartości domyślne do desc Kolejność sortowania według znacznika czasu created_at obiektów. asc dla kolejności rosnącej i desc dla kolejności malejącej.
after string Opcjonalnie Kursor do użycia w stronicowaniu. after jest identyfikatorem obiektu definiującym miejsce na liście. Jeśli na przykład wykonasz żądanie listy i otrzymasz 100 obiektów, kończąc się obj_foo, kolejne wywołanie może obejmować polecenie after=obj_foo w celu pobrania następnej strony listy.
before string Opcjonalnie Kursor do użycia w stronicowaniu. before jest identyfikatorem obiektu definiującym miejsce na liście. Jeśli na przykład wykonasz żądanie listy i otrzymasz 100 obiektów, kończąc się obj_foo, kolejne wywołanie może zawierać wartość before=obj_foo w celu pobrania poprzedniej strony listy.

Zwraca

Lista obiektów asystenta

Przykładowe asystenty listy

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

Pobieranie asystenta

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Pobiera asystenta.

Parametry ścieżki

Parametr Type Wymagania opis
assistant_id string Wymagania Identyfikator asystenta do pobrania.

Zwroty

Obiekt asystenta pasujący do określonego identyfikatora.

Przykładowy asystent pobierania

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

Modyfikowanie asystenta

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Modyfikuje asystenta.

Parametry ścieżki

Parametr Type Wymagania opis
assistant_id string Wymagania Identyfikator asystenta, do którego należy plik.

Treść żądania

Parametr Type Wymagania opis
model Opcjonalnie Nazwa wdrożenia modelu do użycia.
name ciąg lub wartość null Opcjonalnie Nazwa asystenta. Maksymalna długość to 256 znaków.
description ciąg lub wartość null Opcjonalnie Opis asystenta. Maksymalna długość to 512 znaków.
instructions ciąg lub wartość null Opcjonalnie Instrukcje systemowe używane przez asystenta. Maksymalna długość to 32768 znaków.
tools tablica Opcjonalnie Wartości domyślne to []. Lista narzędzi włączonych w asystencie. Może istnieć maksymalnie 128 narzędzi na asystenta. Narzędzia mogą być typami code_interpreter lub funkcjami. function Opis może mieć maksymalnie 1024 znaki.
metadata map Opcjonalnie Zestaw 16 par klucz-wartość, które można dołączyć do obiektu. Może to być przydatne do przechowywania dodatkowych informacji o obiekcie w formacie ustrukturyzowanym. Klucze mogą mieć długość maksymalnie 64 znaków, a wartości mogą mieć długość maksymalnie 512 znaków.
temperature liczba lub wartość null Opcjonalnie Wartość domyślna to 1. Określa temperaturę próbkowania do użycia z zakresu od 0 do 2. Wyższe wartości, takie jak 0,8, sprawią, że dane wyjściowe będą bardziej losowe, a niższe wartości, takie jak 0,2, sprawią, że będzie bardziej skoncentrowany i deterministyczny.
top_p liczba lub wartość null Opcjonalnie Wartość domyślna to 1. Alternatywą dla próbkowania z temperaturą, nazywaną próbkowaniem jądra, gdzie model uwzględnia wyniki tokenów z top_p masą prawdopodobieństwa. Dlatego 0,1 oznacza, że uwzględniane są tylko tokeny składające się z pierwszej masy prawdopodobieństwa o 10%. Ogólnie zalecamy zmianę tej wartości lub temperatury, ale nie obu.
response_format ciąg lub obiekt Opcjonalnie Określa format, który model musi wyświetlić. Zgodny z GPT-4 Turbo i wszystkimi modelami GPT-3.5 Turbo od gpt-3.5-turbo-1106. Ustawienie tego parametru w celu { "type": "json_object" } włączenia trybu JSON, co gwarantuje, że komunikat generowany przez model jest prawidłowym kodem JSON. Co ważne, w przypadku korzystania z trybu JSON należy również poinstruować model, aby samodzielnie wygenerował kod JSON przy użyciu komunikatu systemowego lub użytkownika. Bez tej instrukcji model może wygenerować niekończący się strumień białych znaków, dopóki generowanie nie osiągnie limitu tokenu, co skutkuje długotrwałym i pozornie "zablokowanym" żądaniem. Ponadto zawartość wiadomości może zostać częściowo odcięta w przypadku użycia finish_reason="length"elementu , co oznacza przekroczenie max_tokens generacji lub przekroczenie maksymalnej długości kontekstu konwersacji.
tool_resources obiekt Opcjonalnie Zestaw zasobów używanych przez narzędzia asystenta. Zasoby są specyficzne dla typu narzędzia. Na przykład code_interpreter narzędzie wymaga listy identyfikatorów plików, a file_search narzędzie wymaga listy identyfikatorów magazynów wektorów.

Zwroty

Zmodyfikowany obiekt asystenta.

Przykładowy asystent modyfikacji

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
)

print(my_updated_assistant)

Usuwanie asystenta

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Usuń asystenta.

Parametry ścieżki

Parametr Type Wymagania opis
assistant_id string Wymagania Identyfikator asystenta, do którego należy plik.

Zwroty

Stan usunięcia.

Przykładowy asystent usuwania

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

Dokumentacja interfejsu API przekazywania plików

Asystenci używają tego samego interfejsu API do przekazywania plików jako dostrajania. Podczas przekazywania pliku należy określić odpowiednią wartość dla parametru purpose.

Obiekt Asystenta

Pole Typ opis
id string Identyfikator, do którego można odwoływać się w punktach końcowych interfejsu API.
object string Typ obiektu, który jest zawsze asystentem.
created_at integer Sygnatura czasowa systemu Unix (w sekundach) dla momentu utworzenia asystenta.
name ciąg lub wartość null Nazwa asystenta. Maksymalna długość to 256 znaków.
description ciąg lub wartość null Opis asystenta. Maksymalna długość to 512 znaków.
model string Nazwa nazwy wdrożenia modelu do użycia.
instructions ciąg lub wartość null Instrukcje systemowe używane przez asystenta. Maksymalna długość to 32768 znaków.
tools tablica Lista narzędzi włączona w asystencie. Może istnieć maksymalnie 128 narzędzi na asystenta. Narzędzia mogą być typami code_interpreter lub funkcjami. function Opis może mieć maksymalnie 1024 znaki.
metadata map Zestaw 16 par klucz-wartość, które można dołączyć do obiektu. Może to być przydatne do przechowywania dodatkowych informacji o obiekcie w formacie ustrukturyzowanym. Klucze mogą mieć długość maksymalnie 64 znaków, a wartości mogą mieć długość maksymalnie 512 znaków.
temperature liczba lub wartość null Wartość domyślna to 1. Określa temperaturę próbkowania do użycia z zakresu od 0 do 2. Wyższe wartości, takie jak 0,8, sprawią, że dane wyjściowe będą bardziej losowe, a niższe wartości, takie jak 0,2, sprawią, że będzie bardziej skoncentrowany i deterministyczny.
top_p liczba lub wartość null Wartość domyślna to 1. Alternatywą dla próbkowania z temperaturą, nazywaną próbkowaniem jądra, gdzie model uwzględnia wyniki tokenów z top_p masą prawdopodobieństwa. Dlatego 0,1 oznacza, że uwzględniane są tylko tokeny składające się z pierwszej masy prawdopodobieństwa o 10%. Ogólnie zalecamy zmianę tej wartości lub temperatury, ale nie obu.
response_format ciąg lub obiekt Określa format, który model musi wyświetlić. Zgodny z GPT-4 Turbo i wszystkimi modelami GPT-3.5 Turbo od gpt-3.5-turbo-1106. Ustawienie tego parametru w celu { "type": "json_object" } włączenia trybu JSON, co gwarantuje, że komunikat generowany przez model jest prawidłowym kodem JSON. Co ważne, w przypadku korzystania z trybu JSON należy również poinstruować model, aby samodzielnie wygenerował kod JSON przy użyciu komunikatu systemowego lub użytkownika. Bez tej instrukcji model może wygenerować niekończący się strumień białych znaków, dopóki generowanie nie osiągnie limitu tokenu, co skutkuje długotrwałym i pozornie "zablokowanym" żądaniem. Ponadto zawartość wiadomości może zostać częściowo odcięta w przypadku użycia finish_reason="length"elementu , co oznacza przekroczenie max_tokens generacji lub przekroczenie maksymalnej długości kontekstu konwersacji.
tool_resources obiekt Zestaw zasobów używanych przez narzędzia asystenta. Zasoby są specyficzne dla typu narzędzia. Na przykład code_interpreter narzędzie wymaga listy identyfikatorów plików, a file_search narzędzie wymaga listy identyfikatorów magazynów wektorów.