Sdílet prostřednictvím


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

Poznámka:

  • Hledání souborů může ingestovat až 10 000 souborů na asistenta – 500krát více než dříve. Je to rychlé, podporuje paralelní dotazy prostřednictvím vícevláknového vyhledávání a vylepšené ř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í spuštění

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

Vytvořte spuštění.

Parametr cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna pro vytvoření zprávy.

Text požadavku

Name Type Požadováno Popis
assistant_id string Požaduje se ID pomocníka, který se má použít ke spuštění tohoto spuštění.
model řetězec nebo null Volitelné Název nasazení modelu, který se má použít ke spuštění tohoto spuštění. Pokud je zde zadaná hodnota, přepíše se název nasazení modelu přidružený k asistentovi. Pokud ne, použije se název nasazení modelu přidružený k asistentovi.
instructions řetězec nebo null Volitelné Přepíše pokyny asistenta. To je užitečné při úpravě chování na základě spuštění.
tools pole nebo null Volitelné Přepište nástroje, které může pomocník použít pro toto spuštění. To je užitečné při úpravě chování na základě spuštění.
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ů.

Návraty

Objekt spuštění.

Příklad vytvoření žádosti o spuštění

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

run = client.beta.threads.runs.create(
  thread_id="thread_abc123",
  assistant_id="asst_abc123"
)
print(run)

Vytvoření vlákna a spuštění

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

Vytvořte vlákno a spusťte ho v jednom požadavku.

Text požadavku

Name Type Požadováno Popis
assistant_id string Požaduje se ID pomocníka, který se má použít ke spuštění tohoto spuštění.
thread objekt Volitelné
model řetězec nebo null Volitelné ID názvu nasazení modelu, který se má použít ke spuštění tohoto spuštění. Pokud je zde zadaná hodnota, přepíše se název nasazení modelu přidružený k asistentovi. Pokud ne, použije se název nasazení modelu přidružený k asistentovi.
instructions řetězec nebo null Volitelné Přepište výchozí systémovou zprávu asistenta. To je užitečné při úpravě chování na základě spuštění.
tools pole nebo null Volitelné Přepište nástroje, které může pomocník použít pro toto spuštění. To je užitečné při úpravě chování na základě spuštění.
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ů.

Návraty

Objekt spuštění.

Příklad vytvoření vlákna a spuštění požadavku

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

run = client.beta.threads.create_and_run(
  assistant_id="asst_abc123",
  thread={
    "messages": [
      {"role": "user", "content": "Explain deep learning to a 5 year old."}
    ]
  }
)

Spuštění seznamu

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

Vrátí seznam spuštění patřících do vlákna.

Parametr cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, ke kterému spuštění patří.

Parametry dotazu

Name Type Požadováno Popis
limit integer Volitelné – výchozí hodnota je 20. 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í poté 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í předtím 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ů spuštění

Příklad žádosti o spuštění seznamu

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

runs = client.beta.threads.runs.list(
  "thread_abc123"
)
print(runs)

Vypsat kroky spuštění

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2024-05-01-preview

Vrátí seznam kroků patřících ke spuštění.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, ke kterému spuštění patří.
run_id řetězec Požaduje se ID spuštění přidruženého k krokům spuštění, které se mají dotazovat.

Parametry dotazů

Name Type Požadováno Popis
limit integer Volitelné – výchozí hodnota je 20. 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í poté 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í předtím 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

Seznamobjektůch

Příklad požadavku na kroky spuštění seznamu

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

run_steps = client.beta.threads.runs.steps.list(
    thread_id="thread_abc123",
    run_id="run_abc123"
)
print(run_steps)

Načtení spuštění

from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

Načte spuštění.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, které bylo spuštěno.
run_id řetězec Požaduje se ID spuštění, které se má načíst.

Návraty

Objekt spuštění odpovídající zadanému ID spuštění.

Příklad požadavku na kroky spuštění seznamu

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

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

Načtení kroku spuštění

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2024-05-01-preview

Načte krok spuštění.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, do kterého patří krok spuštění a spuštění.
run_id řetězec Požaduje se ID spuštění, do kterého krok spuštění patří.
step_id řetězec Požaduje se ID kroku spuštění, který se má načíst.

Návraty

Objekt kroku spuštění odpovídající zadanému ID.

Příklad požadavku na načtení kroků spuštění

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

run_step = client.beta.threads.runs.steps.retrieve(
    thread_id="thread_abc123",
    run_id="run_abc123",
    step_id="step_abc123"
)
print(run_step)

Upravit spuštění

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-05-01-preview

Upraví spuštění.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, které bylo spuštěno.
run_id řetězec Požaduje se ID spuštění, které chcete upravit.

Text požadavku

Name Type Požadováno Popis
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ů.

Návraty

Upravený objekt spuštění odpovídající zadanému ID.

Příklad úpravy žádosti o spuštění

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

run = client.beta.threads.runs.update(
  thread_id="thread_abc123",
  run_id="run_abc123",
  metadata={"user_id": "user_abc123"},
)
print(run)

Odeslání výstupů nástroje ke spuštění

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2024-05-01-preview

Když má spuštění stav requires_action a required_action.type je submit_tool_outputs, tento koncový bod se dá použít k odeslání výstupů z volání nástroje po dokončení. Všechny výstupy musí být odeslány v jednom požadavku.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, do kterého toto spuštění patří.
run_id řetězec Požaduje se ID spuštění, které vyžaduje odeslání výstupu nástroje.

Text požadavku

Name Type Požadováno Popis
tool_outputs pole Požaduje se Seznam nástrojů, pro které se odesílají výstupy.

Návraty

Upravený objekt spuštění odpovídající zadanému ID.

Příklad výstupů nástroje pro odeslání pro spuštění požadavku

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

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id="thread_abc123",
  run_id="run_abc123",
  tool_outputs=[
    {
      "tool_call_id": "call_abc123",
      "output": "28C"
    }
  ]
)
print(run)

Zrušení spuštění

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2024-05-01-preview

Zruší spuštění, které je in_progress.

Parametry cesty

Parametr Type Požadováno Popis
thread_id string Požaduje se ID vlákna, do kterého toto spuštění patří.
run_id řetězec Požaduje se ID spuštění, které chcete zrušit.

Návraty

Upravený objekt spuštění odpovídající zadanému ID.

Příklad výstupů nástroje pro odeslání pro spuštění požadavku

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

run = client.beta.threads.runs.cancel(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

Spuštění objektu

Představuje spuštění ve vlákně.

Name 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 thread.run.
created_at integer Časové razítko unixu (v sekundách) pro vytvoření spuštění.
thread_id string ID vlákna, na které bylo spuštěno jako součást tohoto spuštění.
assistant_id string ID asistenta použitého ke spuštění tohoto spuštění.
status string Stav spuštění, který může být buď , , , , , , failed, , , completednebo expired. cancelledcancellingrequires_actionin_progressqueued
required_action objekt nebo null Podrobnosti o akci potřebné k pokračování ve spuštění Pokud není vyžadována žádná akce, bude mít hodnotu null.
last_error objekt nebo null Poslední chyba přidružená k tomuto spuštění. Pokud nedojde k žádným chybám, bude mít hodnotu null.
expires_at integer Časové razítko unixu (v sekundách) pro vypršení platnosti spuštění.
started_at celé číslo nebo null Časové razítko unixu (v sekundách) pro spuštění spuštění.
cancelled_at celé číslo nebo null Časové razítko unixu (v sekundách) po zrušení spuštění.
failed_at celé číslo nebo null Časové razítko unixu (v sekundách) pro dobu, kdy se spuštění nezdařilo.
completed_at celé číslo nebo null Časové razítko unixu (v sekundách) pro dokončení spuštění.
model string Název nasazení modelu, který pomocník použil pro toto spuštění.
instructions string Pokyny, které pomocník použil pro toto spuštění.
tools pole Seznam nástrojů, které pomocník použil pro toto spuštění.
file_ids pole Seznam IDsouborůch
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ů.
tool_choice řetězec nebo objekt Určuje, který (pokud existuje) nástroj, který model volá. none znamená, že model nebude volat žádné nástroje a místo toho vygeneruje zprávu. auto je výchozí hodnota a znamená, že model může vybrat mezi generováním zprávy nebo voláním nástroje. Určení konkrétního nástroje, například {"type": "file_search"} nebo {"type": "function", "function": {"name": "my_function"}} vynutí model, aby tento nástroj volal.
max_prompt_tokens celé číslo nebo null Maximální počet výzev tokenů zadaných k použití v průběhu spuštění.
max_completion_tokens celé číslo nebo null Maximální počet tokenů dokončení určených k použití v průběhu spuštění.
usage objekt nebo null Statistiky využití související se spuštěním Tato hodnota bude null, pokud spuštění není v terminálovém stavu (například in_progress). queued

Spuštění objektu kroku

Představuje krok při spuštění spuštění.

Name Typ Description
id string Identifikátor kroku spuštění, na který lze odkazovat v koncových bodech rozhraní API.
object string Typ objektu, který je vždy thread.run.step.
created_at integer Časové razítko unixu (v sekundách) pro vytvoření kroku spuštění.
assistant_id string ID asistenta přidruženého ke kroku spuštění.
thread_id string ID vlákna, které bylo spuštěno.
run_id string ID spuštění, ve které je tento krok spuštění součástí.
type string Typ kroku spuštění, který může být message_creation nebo tool_calls.
status string Stav kroku spuštění, který může být buď in_progress, cancelled, failed, completed, nebo expired.
step_details objekt Podrobnosti o kroku spuštění
last_error objekt nebo null Poslední chyba přidružená k tomuto kroku spuštění Pokud nedojde k žádným chybám, bude mít hodnotu null.
expired_at celé číslo nebo null Časové razítko unixu (v sekundách) pro vypršení platnosti kroku spuštění. Pokud vypršela platnost nadřazeného spuštění, považuje se za prošlý krok.
cancelled_at celé číslo nebo null Časové razítko unixu (v sekundách) po zrušení kroku spuštění.
failed_at celé číslo nebo null Časové razítko unixu (v sekundách) pro selhání kroku spuštění.
completed_at celé číslo nebo null Časové razítko unixu (v sekundách) pro dokončení kroku spuštění.
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ů.

Streamování výsledku spuštění (Preview)

Streamujte výsledek spuštění nebo obnovení spuštění po odeslání výstupů nástroje. Události můžete streamovat po:

Pokud chcete streamovat výsledek, předejte "stream": true při vytváření spuštění. Odpovědí bude stream událostí odeslaných serverem.

Příklad streamování

from typing_extensions import override
from openai import AssistantEventHandler
 
# First, we create a EventHandler class to define
# how we want to handle the events in the response stream.
 
class EventHandler(AssistantEventHandler):    
  @override
  def on_text_created(self, text) -> None:
    print(f"\nassistant > ", end="", flush=True)
      
  @override
  def on_text_delta(self, delta, snapshot):
    print(delta.value, end="", flush=True)
      
  def on_tool_call_created(self, tool_call):
    print(f"\nassistant > {tool_call.type}\n", flush=True)
  
  def on_tool_call_delta(self, delta, snapshot):
    if delta.type == 'code_interpreter':
      if delta.code_interpreter.input:
        print(delta.code_interpreter.input, end="", flush=True)
      if delta.code_interpreter.outputs:
        print(f"\n\noutput >", flush=True)
        for output in delta.code_interpreter.outputs:
          if output.type == "logs":
            print(f"\n{output.logs}", flush=True)
 
# Then, we use the `create_and_stream` SDK helper 
# with the `EventHandler` class to create the Run 
# and stream the response.
 
with client.beta.threads.runs.stream(
  thread_id=thread.id,
  assistant_id=assistant.id,
  instructions="Please address the user as Jane Doe. The user has a premium account.",
  event_handler=EventHandler(),
) as stream:
  stream.until_done()

Objekt Delta zprávy

Představuje rozdíl zprávy. Například všechna změněná pole ve zprávě během streamování.

Name Typ Description
id string Identifikátor zprávy, na kterou lze odkazovat v koncových bodech rozhraní API.
object string Typ objektu, který je vždy thread.message.delta.
delta objekt Rozdíl obsahující pole, která se změnila ve zprávě.

Objekt Delta kroku spuštění

Představuje rozdílový krok spuštění. Například všechna změněná pole v kroku spuštění během streamování.

Name Typ Description
id string Identifikátor kroku spuštění, na který lze odkazovat v koncových bodech rozhraní API.
object string Typ objektu, který je vždy thread.run.step.delta.
delta objekt Rozdíl obsahující pole, která se změnila v kroku spuštění

Události streamu pomocníka

Představuje událost vygenerovaná při streamování spuštění. Každá událost v streamu událostí odeslaných serverem má událost a datovou vlastnost:

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

Události se vygenerují při každém vytvoření nového objektu, přechodu na nový stav nebo se streamují v částech (rozdíly). Například thread.run.created se vygeneruje při vytvoření nového spuštění, thread.run.completed po dokončení spuštění atd. Když se Pomocník rozhodne vytvořit zprávu během spuštění, vygenerujeme thread.message.created událost, thread.message.in_progress událost, mnoho vláken.message.delta a nakonec událost thread.message.completed .

Name Typ Popis
thread.created data je vlákno. Nastane při vytvoření nového vlákna.
thread.run.created data je spuštění. Nastane při vytvoření nového spuštění.
thread.run.queued data je spuštění. Nastane, když se spuštění přesune do stavu ve frontě.
thread.run.in_progress data je spuštění. Nastane, když se spuštění přesune do in_progress stavu.
thread.run.requires_action data je spuštění. Nastane, když se spuštění přesune do requires_action stavu.
thread.run.completed data je spuštění. Nastane při dokončení spuštění.
thread.run.failed data je spuštění. Nastane, když se spuštění nezdaří.
thread.run.cancelling data je spuštění. Nastane, když se spuštění přesune do cancelling stavu.
thread.run.cancelled data je spuštění. Nastane při zrušení spuštění.
thread.run.expired data je spuštění. Nastane, když vyprší platnost spuštění.
thread.run.step.created data je krok spuštění. Nastane při vytvoření kroku spuštění.
thread.run.step.in_progress data je krok spuštění. Nastane, když se krok spuštění přesune do in_progress stavu.
thread.run.step.delta data je rozdílový krok spuštění. Nastane, když se streamují části kroku spuštění.
thread.run.step.completed data je krok spuštění. Nastane při dokončení kroku spuštění.
thread.run.step.failed data je krok spuštění. Nastane, když selže krok spuštění.
thread.run.step.cancelled data je krok spuštění. Nastane při zrušení kroku spuštění.
thread.run.step.expired data je krok spuštění. Nastane, když vyprší platnost kroku spuštění.
thread.message.created data je zpráva. Nastane při vytvoření zprávy.
thread.message.in_progress data je zpráva. Nastane, když se zpráva přesune do in_progress stavu.
thread.message.delta data je rozdíl zpráv. Nastane, když se streamují části zprávy.
thread.message.completed data je zpráva. Nastane při dokončení zprávy.
thread.message.incomplete data je zpráva. Nastane, když zpráva skončí před dokončením.
error data je chyba. Nastane, když dojde k chybě. K tomu může dojít kvůli vnitřní chybě serveru nebo vypršení časového limitu.
done data Je [DONE] Nastane, když datový proud skončí.