Freigeben über

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 256,000 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. Eine function Beschreibung kann maximal 1.024 Zeichen umfassen.
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.
tool_resources Objekt Optional Eine Reihe von Ressourcen, die von den Tools des Assistenten verwendet werden. Die Ressourcen sind spezifisch für den Tooltyp. Beispielsweise erfordert das Tool code_interpreter eine Liste mit Datei-IDs, während das Tool file_search eine Liste mit Vektorspeicher-IDs erfordert.

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

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-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

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

Assistent abrufen

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-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-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

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

Assistent ändern

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-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. Eine function Beschreibung kann maximal 1.024 Zeichen umfassen.
metadata Karte 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.
temperature 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.
tool_resources Objekt Optional Eine Reihe von Ressourcen, die von den Tools des Assistenten verwendet werden. Die Ressourcen sind spezifisch für den Tooltyp. Beispielsweise erfordert das Tool code_interpreter eine Liste mit Datei-IDs, während das Tool file_search eine Liste mit Vektorspeicher-IDs erfordert.

Rückgaben

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-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)

Assistent löschen

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-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-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

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

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. Eine function Beschreibung kann maximal 1.024 Zeichen umfassen.
metadata Karte 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.
temperature Zahl oder NULL 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 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 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.
tool_resources Objekt Eine Reihe von Ressourcen, die von den Tools des Assistenten verwendet werden. Die Ressourcen sind spezifisch für den Tooltyp. Beispielsweise erfordert das Tool code_interpreter eine Liste mit Datei-IDs, während das Tool file_search eine Liste mit Vektorspeicher-IDs erfordert.