Sdílet prostřednictvím

Referenční informace k rozhraní API asistentů (Preview)

  • Článek

Poznámka:

  • Hledání souborů může ingestovat až 10 000 souborů na asistenta – 500krát více než dříve. Je to rychlý způsob, podporuje paralelní dotazy prostřednictvím vícevláknového vyhledávání a vylepšeného řazení a přepisování dotazů.
    • Vektorové úložiště je nový objekt v rozhraní API. Jakmile se soubor přidá do úložiště vektorů, automaticky se parsuje, zachytá a vloží a připraví k hledání. Vektorová úložiště se dají používat napříč asistenty a vlákny, což zjednodušuje správu souborů a fakturaci.
  • Přidali jsme podporu parametru tool_choice , který se dá použít k vynucení použití konkrétního nástroje (například vyhledávání souborů, interpret kódu nebo funkce) v určitém spuštění.

Tento článek obsahuje referenční dokumentaci pro Python a REST pro nové rozhraní API asistentů (Preview). Podrobnější podrobné pokyny najdete v úvodní příručce.

Vytvoření asistenta

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

Vytvořte asistenta s modelem a pokyny.

Text požadavku

Name Type Požadováno Popis
model řetězec Požaduje se Název nasazení modelu, který se má použít.
name řetězec nebo null Volitelné Jméno asistenta. Maximální délka je 256 znaků.
description řetězec nebo null Volitelné Popis asistenta. Maximální délka je 512 znaků.
pokyny řetězec nebo null Volitelné Systémové pokyny, které asistent používá. Maximální délka je 256 000 znaků.
tools pole Volitelné Výchozí hodnota je []. Seznam nástrojů povolených v asistentovi. Na asistenta může být maximálně 128 nástrojů. Nástroje mohou být aktuálně typu code_interpreter, nebo function. Popis function může být maximálně 1 024 znaků.
metadata map Volitelné Sada 16 párů klíč-hodnota, které lze připojit k objektu. To může být užitečné pro ukládání dalších informací o objektu ve strukturovaném formátu. Klíče můžou mít maximálně 64 znaků a hodnoty můžou mít maximálně 512 znaků.
Teplota číslo nebo null Volitelné Výchozí hodnota je 1. Určuje, jakou teplotu vzorkování se má použít, mezi 0 a 2. Vyšší hodnoty jako 0,8 způsobí, že výstup bude náhodnější, zatímco nižší hodnoty, jako je 0,2, zajistí větší zaměření a deterministiku.
top_p číslo nebo null Volitelné Výchozí hodnota je 1. Alternativou k odběru vzorků s teplotou, označovanou jako vzorkování jádra, kde model bere v úvahu výsledky tokenů s top_p hmotností pravděpodobnosti. Hodnota 0,1 tedy znamená, že se považují pouze tokeny, které tvoří 10% hmotnost pravděpodobnosti. Obecně doporučujeme změnit tuto nebo teplotu, ale ne obojí.
response_format řetězec nebo objekt Volitelné Určuje formát, který musí model vypíše. Kompatibilní s GPT-4 Turbo a všemi modely GPT-3.5 Turbo od gpt-3.5-turbo-1106. Nastavením tohoto parametru { "type": "json_object" } povolíte režim JSON, který zaručuje, že zpráva, kterou model vygeneruje, je platný JSON. Důležité je, že pokud používáte režim JSON, musíte také dát modelu pokyn, aby vygeneroval JSON sami pomocí systémové nebo uživatelské zprávy. Bez této instrukce může model vygenerovat nede-endový proud prázdných znaků, dokud generace nedosáhne limitu tokenu, což vede k dlouhotrvajícímu a zdánlivě zablokovanému požadavku. Kromě toho může být obsah zprávy částečně oříznutý, pokud použijete finish_reason="length", což znamená, že generování překročilo max_tokens nebo konverzace překročila maximální délku kontextu.
tool_resources objekt Volitelné Sada prostředků, které používají nástroje asistenta. Prostředky jsou specifické pro typ nástroje. Nástroj například code_interpreter vyžaduje seznam ID souborů, zatímco file_search nástroj vyžaduje seznam ID úložiště vektorů.

typy response_format

string

auto je výchozí hodnota.

object

Možné type hodnoty: text, json_object, json_schema.

json_schema

Name Typ Popis Výchozí Povinné/volitelné
description string Popis formátu odpovědi, který model používá k určení způsobu reakce ve formátu. Volitelné
name string Název formátu odpovědi. Musí být a-z, A-Z, 0-9 nebo obsahovat podtržítka a pomlčky s maximální délkou 64. Požaduje se
schema objekt Schéma pro formát odpovědi popsané jako objekt schématu JSON. Volitelné
strict logická hodnota nebo hodnota null Zda povolit přísné dodržování schématu při generování výstupu. Pokud je nastavená hodnota true, model bude vždy dodržovat přesné schéma definované v schema poli. Pouze podmnožina schématu JSON je podporována, pokud strict je true. false (nepravda) Volitelné

tool_resources vlastnosti

code_interpreter

Name Typ Popis Výchozí
file_ids pole Seznam ID souborů zpřístupněných nástroji code_interpreter K nástroji může být přidruženo maximálně 20 souborů. []

file_search

Name Typ Popis Povinné/volitelné
vector_store_ids pole Vektorové úložiště připojené k tomuto vláknu. K vláknu může být připojeno maximálně 1 vektorové úložiště. Volitelné
vector_stores pole Pomocná rutina pro vytvoření vektorového úložiště s file_ids a jeho připojení k tomuto vláknu. K vláknu může být připojeno maximálně 1 vektorové úložiště. Volitelné

vector_stores

Name Typ Popis Povinné/volitelné
file_ids pole Seznam ID souborů, které se mají přidat do úložiště vektorů. V úložišti vektorů může být maximálně 1 0000 souborů. Volitelné
chunking_strategy objekt Strategie vytváření bloků dat použitá k vytvoření bloků souborů. Pokud není nastavená, použije se automatická strategie. Volitelné
metadata map Sada 16 párů klíč-hodnota, které lze připojit k úložišti vektorů. To může být užitečné pro ukládání dalších informací o vektorovém úložišti ve strukturovaném formátu. Klíče můžou mít maximálně 64 znaků a hodnoty můžou mít maximálně 512 znaků. Volitelné

chunking_strategy

Name Typ Popis Povinné nebo volitelné
Auto Chunking Strategy objekt Výchozí strategie. Tato strategie v současné době používá max_chunk_size_tokens 800 chunk_overlap_tokens 400 type je vždycky auto. Požaduje se
Static Chunking Strategy objekt type Vždy static Požaduje se

Strategie statického vytváření bloků dat

Name Typ Popis Povinné/volitelné
max_chunk_size_tokens integer Maximální počet tokenů v každém bloku dat. Výchozí hodnota je 800. Minimální hodnota je 100 a maximální hodnota je 4096. Požaduje se
chunk_overlap_tokens integer Počet tokenů, které se překrývají mezi bloky dat. Výchozí hodnota je 400. Všimněte si, že překrytí nesmí překročit polovinu .max_chunk_size_tokens Požaduje se

Návraty

Objekt asistenta.

Příklad žádosti o vytvoření asistenta

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

Seznam asistentů

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

Vrátí seznam všech asistentů.

Parametry dotazů

Parametr Type Požadováno Popis
limit integer Volitelné Omezení počtu vrácených objektů. Limit může být v rozsahu 1 až 100 a výchozí hodnota je 20.
order string Volitelné – výchozí hodnoty pro desc Seřaďte pořadí podle časového razítka created_at objektů. asc pro vzestupné pořadí a desc pro sestupné pořadí.
after řetězec Volitelné Kurzor pro použití ve stránkování after je ID objektu, které definuje vaše místo v seznamu. Pokud například vytvoříte požadavek na seznam a obdržíte 100 objektů, končící na obj_foo, může následující volání zahrnovat after=obj_foo, aby se načte další stránka seznamu.
before řetězec Volitelné Kurzor pro použití ve stránkování before je ID objektu, které definuje vaše místo v seznamu. Pokud například vytvoříte požadavek na seznam a obdržíte 100 objektů, končící na obj_foo, může následující volání zahrnovat před=obj_foo, aby bylo možné načíst předchozí stránku seznamu.

Návraty

Seznam objektů pomocníka

Příklady pomocníků se seznamem

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)

Načíst asistenta

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

Načte asistenta.

Parametry cesty

Parametr Type Požadováno Popis
assistant_id string Požaduje se ID asistenta, který se má načíst.

Vrácení

Objekt asistenta odpovídající zadanému ID.

Příklad pomocníka pro načtení

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)

Úprava asistenta

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

Upraví asistenta.

Parametry cesty

Parametr Type Požadováno Popis
assistant_id řetězec Požaduje se ID asistenta, do které soubor patří.

Text požadavku

Parametr Type Požadováno Popis
model Volitelné Název nasazení modelu, který se má použít.
name řetězec nebo null Volitelné Jméno asistenta. Maximální délka je 256 znaků.
description řetězec nebo null Volitelné Popis asistenta. Maximální délka je 512 znaků.
instructions řetězec nebo null Volitelné Systémové pokyny, které asistent používá. Maximální délka je 32768 znaků.
tools pole Volitelné Výchozí hodnota je []. Seznam nástrojů povolených v asistentovi. Na asistenta může být maximálně 128 nástrojů. Nástroje můžou být typu code_interpreter nebo funkce. Popis function může být maximálně 1 024 znaků.
metadata map Volitelné Sada 16 párů klíč-hodnota, které lze připojit k objektu. To může být užitečné pro ukládání dalších informací o objektu ve strukturovaném formátu. Klíče můžou mít maximálně 64 znaků a hodnoty můžou mít maximálně 512 znaků.
temperature číslo nebo null Volitelné Výchozí hodnota je 1. Určuje, jakou teplotu vzorkování se má použít, mezi 0 a 2. Vyšší hodnoty jako 0,8 způsobí, že výstup bude náhodnější, zatímco nižší hodnoty, jako je 0,2, zajistí větší zaměření a deterministiku.
top_p číslo nebo null Volitelné Výchozí hodnota je 1. Alternativou k odběru vzorků s teplotou, označovanou jako vzorkování jádra, kde model bere v úvahu výsledky tokenů s top_p hmotností pravděpodobnosti. Hodnota 0,1 tedy znamená, že se považují pouze tokeny, které tvoří 10% hmotnost pravděpodobnosti. Obecně doporučujeme změnit tuto nebo teplotu, ale ne obojí.
response_format řetězec nebo objekt Volitelné Určuje formát, který musí model vypíše. Kompatibilní s GPT-4 Turbo a všemi modely GPT-3.5 Turbo od gpt-3.5-turbo-1106. Nastavením tohoto parametru { "type": "json_object" } povolíte režim JSON, který zaručuje, že zpráva, kterou model vygeneruje, je platný JSON. Důležité je, že pokud používáte režim JSON, musíte také dát modelu pokyn, aby vygeneroval JSON sami pomocí systémové nebo uživatelské zprávy. Bez této instrukce může model vygenerovat nede-endový proud prázdných znaků, dokud generace nedosáhne limitu tokenu, což vede k dlouhotrvajícímu a zdánlivě zablokovanému požadavku. Kromě toho může být obsah zprávy částečně oříznutý, pokud použijete finish_reason="length", což znamená, že generování překročilo max_tokens nebo konverzace překročila maximální délku kontextu.
tool_resources objekt Volitelné Sada prostředků, které používají nástroje asistenta. Prostředky jsou specifické pro typ nástroje. Nástroj například code_interpreter vyžaduje seznam ID souborů, zatímco file_search nástroj vyžaduje seznam ID úložiště vektorů.

Vrácení

Upravený objekt pomocníka.

Příklad úpravy asistenta

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)

Odstranit asistenta

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

Odstraňte asistenta.

Parametry cesty

Parametr Type Požadováno Popis
assistant_id string Požaduje se ID asistenta, do které soubor patří.

Vrácení

Stav odstranění

Příklad pomocníka pro odstranění

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)

Referenční informace k rozhraní API pro nahrání souborů

Asistenti používají stejné rozhraní API pro nahrávání souborů jako vyladění. Při nahrávání souboru musíte zadat odpovídající hodnotu pro parametr účelu.

Objekt Pomocníka

Pole Typ Description
id string Identifikátor, na který se dá odkazovat v koncových bodech rozhraní API.
object string Typ objektu, který je vždy pomocníkem.
created_at integer Časové razítko unixu (v sekundách) pro vytvoření asistenta.
name řetězec nebo null Jméno asistenta. Maximální délka je 256 znaků.
description řetězec nebo null Popis asistenta. Maximální délka je 512 znaků.
model string Název názvu nasazení modelu, který se má použít.
instructions řetězec nebo null Systémové pokyny, které asistent používá. Maximální délka je 32768 znaků.
tools pole Seznam nástrojů povolených v asistentovi. Na asistenta může být maximálně 128 nástrojů. Nástroje můžou být typu code_interpreter nebo funkce. Popis function může být maximálně 1 024 znaků.
metadata map Sada 16 párů klíč-hodnota, které lze připojit k objektu. To může být užitečné pro ukládání dalších informací o objektu ve strukturovaném formátu. Klíče můžou mít maximálně 64 znaků a hodnoty můžou mít maximálně 512 znaků.
temperature číslo nebo null Výchozí hodnota je 1. Určuje, jakou teplotu vzorkování se má použít, mezi 0 a 2. Vyšší hodnoty jako 0,8 způsobí, že výstup bude náhodnější, zatímco nižší hodnoty, jako je 0,2, zajistí větší zaměření a deterministiku.
top_p číslo nebo null Výchozí hodnota je 1. Alternativou k odběru vzorků s teplotou, označovanou jako vzorkování jádra, kde model bere v úvahu výsledky tokenů s top_p hmotností pravděpodobnosti. Hodnota 0,1 tedy znamená, že se považují pouze tokeny, které tvoří 10% hmotnost pravděpodobnosti. Obecně doporučujeme změnit tuto nebo teplotu, ale ne obojí.
response_format řetězec nebo objekt Určuje formát, který musí model vypíše. Kompatibilní s GPT-4 Turbo a všemi modely GPT-3.5 Turbo od gpt-3.5-turbo-1106. Nastavením tohoto parametru { "type": "json_object" } povolíte režim JSON, který zaručuje, že zpráva, kterou model vygeneruje, je platný JSON. Důležité je, že pokud používáte režim JSON, musíte také dát modelu pokyn, aby vygeneroval JSON sami pomocí systémové nebo uživatelské zprávy. Bez této instrukce může model vygenerovat nede-endový proud prázdných znaků, dokud generace nedosáhne limitu tokenu, což vede k dlouhotrvajícímu a zdánlivě zablokovanému požadavku. Kromě toho může být obsah zprávy částečně oříznutý, pokud použijete finish_reason="length", což znamená, že generování překročilo max_tokens nebo konverzace překročila maximální délku kontextu.
tool_resources objekt Sada prostředků, které používají nástroje asistenta. Prostředky jsou specifické pro typ nástroje. Nástroj například code_interpreter vyžaduje seznam ID souborů, zatímco file_search nástroj vyžaduje seznam ID úložiště vektorů.