Share via

Referenz zur Assistants-API (Vorschau)

  • Artikel

Hinweis

  • Die Dateisuche kann bis zu 10.000 Dateien pro Assistent erfassen – 500 mal mehr als bisher. Sie ist schnell, unterstützt parallele Abfragen durch Multithreadsuchvorgänge und beinhaltet verbesserte Funktionen für Neusortierung und das Umschreiben von Abfragen.
    • Der Vektorspeicher ist ein neues Objekt in der API. Sobald eine Datei einem Vektorspeicher hinzugefügt wurde, wird sie automatisch geparst, aufgeteilt und eingebettet, damit sie durchsucht werden kann. Vektorspeicher können über Assistenten und Threads hinweg verwendet werden und vereinfachen so die Dateiverwaltung und Abrechnung.
  • Wir haben Unterstützung für den Parameter tool_choice hinzugefügt. Dieser kann verwendet werden, um die Nutzung eines bestimmten Tools (z. B. Dateisuche, Codeinterpreter oder eine Funktion) in einer bestimmten Ausführung zu erzwingen.

Dieser Artikel enthält eine Referenzdokumentation für Python und REST für die neue Assistants-API (Vorschau). Ausführlichere Schrittanleitungen finden Sie im Leitfaden für erste Schritte.

Erstellen eines Assistenten

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

Erstellen Sie einen Assistenten mit einem Modell und Anweisungen.

Anforderungstext

Name Type Erforderlich Beschreibung
model Zeichenfolge Erforderlich Modellimplementierungsname des zu verwendenden Modells.
name Zeichenfolge oder null Optional Der Name des Assistenten. Die maximale Länge beträgt 256 Zeichen.
Beschreibung Zeichenfolge oder null Optional Die Beschreibung des Assistenten. Die maximale Länge beträgt 512 Zeichen.
Setup Zeichenfolge oder null Optional Die Systemanweisungen, die der Assistent verwendet. Die maximale Länge beträgt 32.768 Zeichen.
Tools array Optional Der Standardwert lautet []. Eine Liste der im Assistenten aktivierten Tools. Jeder Assistent kann maximal 128 Tools enthalten. Tools können derzeit vom Typ code_interpreter oder function sein.
file_ids array Optional Der Standardwert lautet []. Eine Liste der an diesen Assistenten angefügten Datei-IDs. An Assistenten können maximal 20 Dateien angefügt werden. Die Dateien werden nach ihrem Erstellungsdatum in aufsteigender Reihenfolge sortiert.
metadata map Optional 16 Schlüssel-Wert-Paare, die an ein Objekt angefügt werden können. Dies kann hilfreich sein, um zusätzliche Informationen zum Objekt in einem strukturierten Format zu speichern. Schlüssel dürfen maximal 64 Zeichen und Werte dürfen höchstens 512 Zeichen lang sein.
Temperatur Zahl oder NULL Optional Der Standardwert lautet 1. Bestimmt die zu verwendende Temperatur für die Stichprobenentnahme zwischen 0 und 2. Durch höhere Werte wie 0,8 wird die Ausgabe zufälliger, während sie durch niedrigere Werte wie 0,2 fokussierter und deterministischer wird.
top_p Zahl oder NULL Optional Der Standardwert lautet 1. Eine Alternative zur Stichprobenentnahme mit Temperatur, die sogenannte Kernstichprobenentnahme (Nucleus Sampling), bei dem das Modell die Ergebnisse der Token mit der Wahrscheinlichkeitsmasse „top_p“ berücksichtigt. Daher bedeutet 0,1, dass nur die Token berücksichtigt werden, die die oberen 10 % der Wahrscheinlichkeitsmasse umfassen. Wir empfehlen im Allgemeinen, dies oder die Temperatur zu ändern, aber nicht beides.
response_format Zeichenfolge oder Objekt Optional Gibt das Format an, das das Modell ausgeben muss. Kompatibel mit GPT-4 Turbo und allen GPT-3.5 Turbo-Modellen seit gpt-3.5-turbo-1106. Wenn Sie diesen Parameter auf { "type": "json_object" } festlegen, wird der JSON-Modus aktiviert, der sicherstellt, dass die vom Modells generierte Meldung gültiger JSON-Code ist. Bei Verwendung des JSON-Modus müssen Sie das Modell auch anweisen, JSON-Code selbst mithilfe einer System- oder einer Benutzermeldung zu erstellen. Ohne diese Anweisung generiert das Modell möglicherweise einen unendlichen Leerzeichenstrom, bis bei der Generierung der Tokengrenzwert erreicht wird. Dies kann zu einer lang andauernden und scheinbar „hängenden“ Anforderung führen. Darüber hinaus kann der Meldungsinhalt teilweise abgeschnitten werden, wenn Sie finish_reason="length" verwenden. Damit wird angegeben, dass bei der Generierung max_tokens überschritten wurde oder die Unterhaltung die maximale Kontextlänge überschritten hat.

Gibt zurück

Ein assistant-Objekt.

Beispiel für das Erstellen einer Assistentenanforderung

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"}]
)

Assistentendatei erstellen

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

Erstellt eine Assistentendatei durch Anfügen von File an einen assistant.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, an den die Datei angefügt werden soll.

Anforderungstext

Name Type Erforderlich Beschreibung
file_id Zeichenfolge Erforderlich Eine Datei-ID (mit purpose="assistants"), die der Assistent verwenden soll. Nützlich für Tools wie Code Interpreter, die auf Dateien zugreifen können.

Gibt zurück

Ein assistant file-Objekt.

Beispiel für das Erstellen einer Assistentendateianforderung

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)

Assistenten auflisten

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

Gibt eine Liste aller Assistenten zurück.

Abfrageparameter

Parameter Type Erforderlich Beschreibung
limit integer Optional Ein Grenzwert für die Anzahl von Objekten, die zurückgegeben werden sollen. Der Grenzwert kann zwischen 1 und 100 liegen. Der Standardwert ist 20.
order Zeichenfolge Optional: Standardwert „desc“ Sortierreihenfolge nach dem Zeitstempel „created_at“ der Objekte. „asc“ für aufsteigende Reihenfolge und „desc“ für absteigende Reihenfolge
after Zeichenfolge Optional Ein Cursor für die Verwendung bei der Paginierung. after ist eine Objekt-ID, die die Position in der Liste definiert. Wenn Sie z. B. eine Listenanforderung senden und 100 Objekte empfangen, die mit „obj_foo“ enden, kann der nachfolgende Aufruf „after=obj_foo“ enthalten, um die nächste Seite der Liste abzurufen.
before Zeichenfolge Optional Ein Cursor für die Verwendung bei der Paginierung. before ist eine Objekt-ID, die die Position in der Liste definiert. Wenn Sie z. B. eine Listenanforderung senden und 100 Objekte empfangen, die mit „obj_foo“ enden, kann der nachfolgende Aufruf „before=obj_foo“ enthalten, um die vorherige Seite der Liste abzurufen.

Gibt zurück

Eine Liste der assistant-Objekte

Beispiel für das Auflisten von Assistenten

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)

Assistentendateien auflisten

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

Gibt eine Liste der Assistentendateien zurück.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, zu dem die Datei gehört.

Abfrageparameter

Parameter Type Erforderlich Beschreibung
limit integer Optional Ein Grenzwert für die Anzahl von Objekten, die zurückgegeben werden sollen. Der Grenzwert kann zwischen 1 und 100 liegen. Der Standardwert ist 20.
order Zeichenfolge Optional: Standardwert „desc“ Sortierreihenfolge nach dem Zeitstempel „created_at“ der Objekte. „asc“ für aufsteigende Reihenfolge und „desc“ für absteigende Reihenfolge
after Zeichenfolge Optional Ein Cursor für die Verwendung bei der Paginierung. after ist eine Objekt-ID, die die Position in der Liste definiert. Wenn Sie z. B. eine Listenanforderung senden und 100 Objekte empfangen, die mit „obj_foo“ enden, kann der nachfolgende Aufruf „after=obj_foo“ enthalten, um die nächste Seite der Liste abzurufen.
before Zeichenfolge Optional Ein Cursor für die Verwendung bei der Paginierung. before ist eine Objekt-ID, die die Position in der Liste definiert. Wenn Sie z. B. eine Listenanforderung senden und 100 Objekte empfangen, die mit „obj_foo“ enden, kann der nachfolgende Aufruf „before=obj_foo“ enthalten, um die vorherige Seite der Liste abzurufen.

Gibt zurück

Eine Liste der assistant file-Objekte

Beispiel für das Auflisten von Assistentendateien

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)

Assistent abrufen

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

Ruft einen Assistenten ab.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des abzurufenden Assistenten.

Rückgabe

Das assistant-Objekt, das der angegebenen ID entspricht.

Beispiel für das Abrufen eines Assistenten

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)

Assistentendatei abrufen

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

Ruft eine Assistentendatei ab.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, zu dem die Datei gehört.
file_id Zeichenfolge Erforderlich Die ID der abzurufenden Datei

Gibt zurück

Das assistant file-Objekt, das der angegebenen ID entspricht.

Beispiel für das Abrufen einer Assistentendatei

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)

Assistent ändern

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

Ändert einen Assistenten.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, zu dem die Datei gehört.

Anforderungstext

Parameter Type Erforderlich Beschreibung
model Optional Der Modellimplementierungsname des zu verwendenden Modells.
name Zeichenfolge oder null Optional Der Name des Assistenten. Die maximale Länge beträgt 256 Zeichen.
description Zeichenfolge oder null Optional Die Beschreibung des Assistenten. Die maximale Länge beträgt 512 Zeichen.
instructions Zeichenfolge oder null Optional Die Systemanweisungen, die der Assistent verwendet. Die maximale Länge beträgt 32.768 Zeichen.
tools array Optional Der Standardwert lautet []. Eine Liste der im Assistenten aktivierten Tools. Jeder Assistent kann maximal 128 Tools enthalten. Tools können vom Typ „code_interpreter“ oder „function“ sein.
file_ids array Optional Der Standardwert lautet []. Eine Liste der an diesen Assistenten angefügten Datei-IDs. An Assistenten können maximal 20 Dateien angefügt werden. Die Dateien werden nach ihrem Erstellungsdatum in aufsteigender Reihenfolge sortiert. Wenn eine Datei zuvor an die Liste angefügt wurde, aber nicht in der Liste angezeigt wird, wird sie aus dem Assistenten gelöscht.
metadata map Optional 16 Schlüssel-Wert-Paare, die an ein Objekt angefügt werden können. Dies kann hilfreich sein, um zusätzliche Informationen zum Objekt in einem strukturierten Format zu speichern. Schlüssel dürfen maximal 64 Zeichen und Werte dürfen höchstens 512 Zeichen lang sein.

Rückgabe

Das geänderte assistant-Objekt.

Beispiel für das Ändern von Assistenten

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)

Assistent löschen

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

Löscht einen Assistenten.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, zu dem die Datei gehört.

Rückgabe

Löschstatus.

Beispiel für das Löschen eines Assistenten

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)

Assistentendatei löschen

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

Löscht eine Assistentendatei.

Pfadparameter

Parameter Type Erforderlich Beschreibung
assistant_id Zeichenfolge Erforderlich Die ID des Assistenten, zu dem die Datei gehört.
file_id Zeichenfolge Erforderlich Die ID der zu löschenden Datei

Rückgabe

Löschstatus der Datei

Beispiel für das Löschen einer Assistentendatei

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)

API-Referenz zum Hochladen von Dateien

Assistenten verwenden für den Datei-Upload die gleiche API wie für die Feinabstimmung. Wenn Sie eine Datei hochladen, müssen Sie einen geeigneten Wert für den Parameter Zweck angeben.

Assistant-Objekt

Feld Typ Beschreibung
id string Der Bezeichner, auf den in API-Endpunkten verwiesen werden kann
object Zeichenfolge Der Objekttyp, der immer „assistant“ ist.
created_at integer Der Unix-Zeitstempel (in Sekunden) des Zeitpunkts, zu dem der Assistent erstellt wurde.
name Zeichenfolge oder null Der Name des Assistenten. Die maximale Länge beträgt 256 Zeichen.
description Zeichenfolge oder null Die Beschreibung des Assistenten. Die maximale Länge beträgt 512 Zeichen.
model Zeichenfolge Name der zu verwendenden Modellimplementierung.
instructions Zeichenfolge oder null Die Systemanweisungen, die der Assistent verwendet. Die maximale Länge beträgt 32.768 Zeichen.
tools array Eine Liste der im Assistenten aktivierten Tools. Jeder Assistent kann maximal 128 Tools enthalten. Tools können vom Typ „code_interpreter“ oder „function“ sein.
file_ids array Eine Liste der an diesen Assistenten angefügten Datei-IDs. An Assistenten können maximal 20 Dateien angefügt werden. Die Dateien werden nach ihrem Erstellungsdatum in aufsteigender Reihenfolge sortiert.
metadata map 16 Schlüssel-Wert-Paare, die an ein Objekt angefügt werden können. Dies kann hilfreich sein, um zusätzliche Informationen zum Objekt in einem strukturierten Format zu speichern. Schlüssel dürfen maximal 64 Zeichen und Werte dürfen höchstens 512 Zeichen lang sein.

Assistentendateiobjekt

Feld Typ Beschreibung
id string Der Bezeichner, auf den in API-Endpunkten verwiesen werden kann
object Zeichenfolge Der Objekttyp, der immer assistant.file ist.
created_at integer Der Unix-Zeitstempel (in Sekunden) für den Zeitpunkt der Erstellung der Assistentendatei.
assistant_id Zeichenfolge Die ID des Assistenten, an den die Datei angefügt ist.