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.

response_format-Typen

string

Der Standardwert lautet auto.

object

Mögliche type-Werte: text, json_object, json_schema.

json_schema

Name Typ Beschreibung Standard Erforderlich/Optional
description Zeichenfolge Eine Beschreibung, wofür das Antwortformat gedacht ist, die vom Modell verwendet wird, um zu bestimmen, wie in dem Format geantwortet werden soll. Optional
name Zeichenfolge Der Name des Antwortformats. Muss aus a–z, A–Z, 0–9 bestehen oder Unterstriche und Bindestriche enthalten, maximale Länge: 64. Erforderlich
schema Objekt Das Schema für das Antwortformat, das als JSON-Schemaobjekt beschrieben wird. Optional
strict boolean oder null Gibt an, ob die strikte Schematreue beim Generieren der Ausgabe aktiviert werden soll. Wenn dieser Wert auf „true“ festgelegt ist, folgt das Modell immer dem genauen Schema, das im Feld schema definiert ist. Nur eine Teilmenge des JSON-Schemas wird unterstützt, wenn strict true ist. false Optional

tool_resources Eigenschaften

code_interpreter

Name Typ Beschreibung Standard
file_ids array Eine Liste mit Datei-IDs, die für das Tool „code_interpreter“ zur Verfügung gestellt wurden. Dem Tool können maximal 20 Dateien zugeordnet sein. []

file_search

Name Typ BESCHREIBUNG Erforderlich/Optional
vector_store_ids array Der an diesen Thread angefügte Vektorspeicher. An den Thread kann maximal ein einzelner Vektorspeicher angefügt werden. Optional
vector_stores array Ein Hilfsprogramm, das dazu dient, einen Vektorspeicher mit Datei-IDs (file_ids) zu erstellen und an diesen Thread anzufügen. An den Thread kann maximal ein einzelner Vektorspeicher angefügt werden. Optional

vector_stores

Name Typ BESCHREIBUNG Erforderlich/Optional
file_ids array Eine Liste der Datei-IDs, die dem Vektorspeicher hinzugefügt werden sollen. Es kann maximal 100.00 Dateien in einem Vektorspeicher geben. Optional
chunking_strategy Objekt Die Segmentierungsstrategie, die verwendet wird, um die Datei(en) in Blöcke zu unterteilen. Wenn kein Wert angegeben ist, wird die automatische Strategie verwendet. Optional
metadata Karte 16 Schlüssel-Wert-Paare, die an einen Vektorspeicher angefügt werden können. Dies kann hilfreich sein, um zusätzliche Informationen zum Vektorspeicher in einem strukturierten Format zu speichern. Schlüssel dürfen maximal 64 Zeichen und Werte dürfen höchstens 512 Zeichen lang sein. Optional

chunking_strategy

Name Typ BESCHREIBUNG Erforderlich/optional
Auto Chunking Strategy Objekt Die Standardstrategie. Diese Strategie verwendet derzeit einen max_chunk_size_tokens-Wert von 800 und einen chunk_overlap_tokens-Wert von 400. type entspricht immer auto. Erforderlich
Static Chunking Strategy Objekt type immer static Erforderlich

Statische Segmentierungsstrategie

Name Typ BESCHREIBUNG Erforderlich/Optional
max_chunk_size_tokens integer Die maximale Anzahl von Token in jedem Block. Der Standardwert ist 800. Der Mindestwert ist 100, und der maximale Wert ist 4096. Erforderlich
chunk_overlap_tokens integer Die Anzahl von Token, die sich zwischen Blöcken überlappen. Der Standardwert ist 400. Beachten Sie, dass die Überlappung nicht größer als die Hälfte des max_chunk_size_tokens-Werts sein darf. Erforderlich

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 type 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.