Dokumentacja interfejsu API asystentów (wersja zapoznawcza)

Uwaga

• Wyszukiwanie plików może pozyskiwać maksymalnie 10 000 plików na asystenta — 500 razy więcej niż wcześniej. Jest szybki, obsługuje zapytania równoległe za pośrednictwem wyszukiwania wielowątkowego i oferuje ulepszone ponowne korbowanie i ponowne zapisywanie zapytań.
  • Magazyn wektorowy to nowy obiekt w interfejsie API. Po dodaniu pliku do magazynu wektorów jest on automatycznie analizowany, fragmentowany i osadzony, gotowy do wyszukiwania. Magazyny wektorowe 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.
file_ids	tablica	Opcjonalnie	Wartości domyślne to []. Lista identyfikatorów plików dołączonych do tego asystenta. Może istnieć maksymalnie 20 plików dołączonych do asystenta. Pliki są uporządkowane według daty utworzenia w kolejności rosnącej.
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.

Zwraca

Obiekt asystenta.

Przykładowe żądanie asystenta tworzenia

Python 1.x

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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"}]
)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

Tworzenie pliku asystenta

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

Utwórz plik asystenta, dołączając element File do elementu assistant.

Parametry ścieżki

Parametr	Type	Wymagania	opis
assistant_id	string	Wymagania	Identyfikator asystenta, do którego powinien zostać dołączony plik.

Treść żądania

Nazwisko	Type	Wymagania	opis
File_id	string	Wymagania	Identyfikator pliku (z identyfikatorem purpose="asystentami"), którego powinien używać asystent. Przydatne w przypadku narzędzi, takich jak code_interpreter, które mogą uzyskiwać dostęp do plików.

Zwraca

Obiekt pliku asystenta.

Przykładowe żądanie utworzenia pliku asystenta

Python 1.x

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

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
       "file_id": "assistant-abc123"
     }'

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

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Wyświetlanie listy plików asystenta

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

Zwraca listę plików asystenta.

Parametry ścieżki

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

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 plików asystenta

Przykładowe pliki asystenta listy

Python 1.x

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

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Pobieranie asystenta

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Pobieranie pliku asystenta

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

Pobiera plik Asystenta.

Parametry ścieżki

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

Zwraca

Obiekt pliku asystenta pasujący do określonego identyfikatora

Przykład pobierania pliku asystenta

Python 1.x

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

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files/{file-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 

Modyfikowanie asystenta

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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.
file_ids	tablica	Opcjonalnie	Wartości domyślne to []. Lista identyfikatorów plików dołączonych do tego asystenta. Może istnieć maksymalnie 20 plików dołączonych do asystenta. Pliki są uporządkowane według daty utworzenia w kolejności rosnącej. Jeśli plik został wcześniej dołączony do listy, ale nie zostanie wyświetlony na liście, zostanie usunięty z asystenta.
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.

Zwroty

Zmodyfikowany obiekt asystenta.

Przykładowy asystent modyfikacji

Python 1.x

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4",
      "file_ids": ["assistant-abc123", "assistant-abc456"]
    }'

Usuwanie asystenta

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

Usuń plik asystenta

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

Usuń plik asystenta.

Parametry ścieżki

Parametr	Type	Wymagania	opis
assistant_id	string	Wymagania	Identyfikator asystenta, do którego należy plik.
file_id	string	Wymagania	Identyfikator pliku do usunięcia

Zwroty

Stan usunięcia pliku

Przykładowy plik asystenta usuwania

Python 1.x

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

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
```  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

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.
file_ids	tablica	Lista identyfikatorów plików dołączonych do tego asystenta. Może istnieć maksymalnie 20 plików dołączonych do asystenta. Pliki są uporządkowane według daty utworzenia w kolejności rosnącej.
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.

Obiekt pliku 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 assistant.file
created_at	integer	Sygnatura czasowa systemu Unix (w sekundach) dla momentu utworzenia pliku asystenta.
assistant_id	string	Identyfikator asystenta, do którego jest dołączony plik.