Korzystanie z interfejsu API odpowiedzi OpenAI Azure

Użyj API odpowiedzi Azure OpenAI, aby generować odpowiedzi stanowe, wielotaktowe. Łączy ona funkcje uzupełniania czatów oraz interfejsu API Asystentów w jedno spójne doświadczenie. Użyj orkiestracji wielu agentów, aby delegować niezależne zadania do równoległych podagentów, albo użyj wyszukiwania narzędzi, aby ładować definicje narzędzi tylko wtedy, gdy model ich potrzebuje. Interfejs API odpowiedzi obsługuje również model napędzający computer-use-previewużycie komputera.

Aby uzyskać pełne opisy parametrów żądań i odpowiedzi, zobacz dokumentację parametrów interfejsu API odpowiedzi.

Wymagania wstępne

  • Wdrożony model Azure OpenAI.
  • Metoda uwierzytelniania:
    • Klucz interfejsu API (na przykład AZURE_OPENAI_API_KEY), lub
    • Microsoft Entra ID (zalecane).
  • Zainstaluj bibliotekę klienta dla swojego języka:
    • Python:pip install openai azure-identity
    • .NET: dotnet add package OpenAI i dotnet add package Azure.Identity
    • JavaScript/TypeScript: npm install openai @azure/identity
    • Java: Dodaj com.openai:openai-java i com.azure:azure-identity do projektu.
  • W przykładach REST ustaw AZURE_OPENAI_API_KEY (przepływ klucza API) lub AZURE_OPENAI_AUTH_TOKEN (przepływ Microsoft Entra ID).

Obsługiwane regiony

Przed uruchomieniem przykładów w tym artykule upewnij się, że region zasobu obsługuje interfejs API Responses. Interfejs API w wersji 1 jest wymagany do uzyskiwania dostępu do najnowszych funkcji. Aby uzyskać szczegółowe informacje, zobacz cykl życia wersji interfejsu API. Aby uzyskać pomoc regionalną dla usługi Agent Foundry, zobacz regionalną tabelę dostępności. Interfejs API Responses jest obecnie dostępny w następujących regionach:

  • australiaeast
  • brazilsouth
  • canadacentral
  • canadaeast
  • centralny
  • eastus
  • eastus2
  • francecentral
  • germanywestcentral
  • italynorth
  • japaneast
  • japanwest
  • koreacentral
  • northcentralus
  • norwayeast
  • polandcentral
  • southafricanorth
  • southcentralus
  • południowo-wschodnia Azja
  • Południowe Indie
  • hiszpaniacentral
  • swedencentral
  • Szwajcaria Północ
  • switzerlandwest
  • uaenorth
  • uksouth
  • ukwest
  • westcentralus
  • Europa Zachodnia
  • westus
  • westus2
  • westus3

Obsługiwane modele

Interfejs API odpowiedzi obsługuje następujące modele:

  • gpt-6.1-terra (Wersja: 2026-10-26)
  • gpt-6.1-sol (Wersja: 2026-09-29)
  • gpt-6-luna (Wersja: 2026-09-22)
  • gpt-6-sol (Wersja: 2026-09-22)
  • gpt-6-astra (Wersja: 2026-09-03)
  • gpt-5.6-sol (Wersja: 2026-07-09)
  • gpt-5.6-terra (Wersja: 2026-07-09)
  • gpt-5.6-luna (Wersja: 2026-07-09)
  • gpt-chat-latest (Wersje: 2026-10-07, 2026-08-06, 2026-06-24, 2026-05-28, 2026-05-05)
  • gpt-5.5 (Wersja: 2026-04-24)
  • gpt-5.4-nano (Wersja: 2026-03-17)
  • gpt-5.4-mini (Wersja: 2026-03-17)
  • gpt-5.4-pro (Wersja:2026-03-05)
  • gpt-5.4 (Wersja:2026-03-05)
  • gpt-5.3-chat (Wersja: 2026-03-03)
  • gpt-5.3-codex (Wersja: 2026-02-24)
  • gpt-5.2-codex (Wersja: 2026-01-14)
  • gpt-5.2 (Wersja: 2025-12-11)
  • gpt-5.2-chat (Wersja: 2025-12-11)
  • gpt-5.2-chat (Wersja: 2026-02-10)
  • gpt-5.1-codex-max (Wersja: 2025-12-04)
  • gpt-5.1 (Wersja: 2025-11-13)
  • gpt-5.1-chat (Wersja: 2025-11-13)
  • gpt-5.1-codex (Wersja: 2025-11-13)
  • gpt-5.1-codex-mini (Wersja: 2025-11-13)
  • gpt-5-pro (Wersja: 2025-10-06)
  • gpt-5-codex (Wersja: 2025-09-11)
  • gpt-5 (Wersja: 2025-08-07)
  • gpt-5-mini (Wersja: 2025-08-07)
  • gpt-5-nano (Wersja: 2025-08-07)
  • gpt-5-chat (Wersja: 2025-08-07)
  • gpt-5-chat (Wersja: 2025-10-03)
  • gpt-5-codex (Wersja: 2025-09-15)
  • gpt-4o(Wersje: 2024-11-20, , 2024-08-062024-05-13)
  • gpt-4o-mini (Wersja: 2024-07-18)
  • computer-use-preview
  • gpt-4.1 (Wersja: 2025-04-14)
  • gpt-4.1-nano (Wersja: 2025-04-14)
  • gpt-4.1-mini (Wersja: 2025-04-14)
  • gpt-image-1 (Wersja: 2025-04-15)
  • gpt-image-1-mini (Wersja: 2025-10-06)
  • gpt-image-1.5 (Wersja: 2025-12-16)
  • gpt-image-2.5-flare (Wersja: 2026-09-09)
  • gpt-image-2.5-sunburst (Wersja: 2026-09-09)
  • o1 (Wersja: 2024-12-17)
  • o3-mini (Wersja: 2025-01-31)
  • o3 (Wersja: 2025-04-16)
  • o4-mini (Wersja: 2025-04-16)

Nie każdy model jest dostępny w każdym obsługiwanym regionie. Sprawdź stronę modeli pod kątem dostępności regionu modelu.

Uwaga

Obecnie niewspierane:

  • Generowanie obrazów za pomocą edycji wieloetapowej i przesyłania strumieniowego.

Istnieje znany problem z następującymi elementami:

  • Plik PDF jako plik wejściowy jest teraz obsługiwany, ale ustawienie przeznaczenia przekazywania plików na user_data nie jest obecnie obsługiwane.
  • Problemy z wydajnością, gdy tryb w tle jest używany z przesyłaniem strumieniowym. Microsoft pracuje nad rozwiązaniem tego problemu.

Generowanie odpowiedzi tekstowej

Wygeneruj prostą odpowiedź tekstową przy użyciu interfejsu API odpowiedzi. Zastąp YOUR-RESOURCE-NAME i MODEL_NAME wartościami wdrożenia.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication (recommended)
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider(),
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)
print(response.model_dump_json(indent=2))

Przykładowa odpowiedź

{
  "id": "resp_67cb32528d6881909eb2859a55e18a85",
  "created_at": 1741369938.0,
  "output_text": "Great! How can I help you today?",
  ...
}

Pobieranie odpowiedzi

Pobierz odpowiedź na podstawie jej identyfikatora z poprzedniego wywołania Responses API.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.retrieve("<response_id>")
print(response.model_dump_json(indent=2))

Przykładowa odpowiedź

{
  "id": "resp_67cb61fa3a448190bcf2c42d96f0d1a8",
  "output_text": "Hello! How can I assist you today?",
  ...
}

Usuwanie odpowiedzi

Domyślnie dane odpowiedzi są przechowywane przez 30 dni. Usuń przechowywaną odpowiedź na podstawie identyfikatora.

import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# API key authentication
client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.delete("<response_id>")
print(response)

# Microsoft Entra ID authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
)
response = client.responses.delete("<response_id>")
print(response)

Szyfrowanie przechowywanych danych odpowiedzi

Gdy interfejs API odpowiedzi utrwala historię komunikatów i powiązaną zawartość, usługa szyfruje te dane w spoczynku. Aby uzyskać wyjaśnienie dotyczące szyfrowania magazynu, zobacz Dane, prywatność i zabezpieczenia modeli sprzedawanych przez Azure w usłudze Microsoft Foundry. Aby uzyskać informacje na temat zakresu obsługi CMK i wymagań wstępnych, zobacz Szyfrowanie przy użyciu klucza zarządzanego przez klienta w usłudze Microsoft Foundry.

To szyfrowanie jest oddzielone od zaszyfrowanych elementów rozumowania zwracanych do aplikacji podczas zarządzania stanem konwersacji przy użyciu store=false.

Łączenie łańcuchów odpowiedzi

Łańcuch zmienia się przez przekazanie poprzedniego identyfikatora odpowiedzi do previous_response_id.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

first_response = client.responses.create(
    model="MODEL_NAME",
    input="Define catastrophic forgetting."
)

second_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=first_response.id,
    input="Explain it for a college freshman."
)

print(second_response.output_text)

Ręczne łączenie odpowiedzi

Alternatywnie możesz ręcznie przenieść elementy wyjściowe do przodu w następnym żądaniu.

import os
from openai import OpenAI

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")  
)

inputs = [{"type": "message", "role": "user", "content": "Define and explain the concept of catastrophic forgetting?"}] 
  
response = client.responses.create(  
    model="gpt-4o",  # replace with your model deployment name  
    input=inputs  
)  
  
inputs += response.output

inputs.append({"role": "user", "type": "message", "content": "Explain this at a level that could be understood by a college freshman"}) 
               

second_response = client.responses.create(
  model="MODEL_NAME",
    input=inputs
)

print(second_response.model_dump_json(indent=2))

Kompaktowanie odpowiedzi

Kompaktowanie zmniejsza kontekst wejściowy przy zachowaniu podstawowego stanu dla późniejszych zmian.

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

compacted = client.responses.compact(
  model="MODEL_NAME",
  input=[
    {"role": "user", "content": "Create a simple landing page for a dog cafe."},
    {
      "id": "msg_001",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "..."}],
    },
  ]
)

follow_up = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add a booking form."}]
)
print(follow_up.output_text)

Kompaktowanie przy użyciu zwracanych elementów

Można skompaktować wszystkie elementy zwracane z poprzednich żądań, takich jak rozumowanie, komunikat, wywołanie funkcji itp.

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/compact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
        "model": "MODEL_NAME",
        "input": [
          {
            "role"   : "user",
            "content": "Create a simple landing page for a dog petting café."
          },
          {
            "id": "msg_001",
            "type": "message",
            "status": "completed",
            "content": [
              {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
              }
            ],
            "role": "assistant"
          }
        ]
    }'

# Use the compacted output as input for the next turn.
next_response = client.responses.create(
  model="MODEL_NAME",
  input=[*compacted.output, {"role": "user", "content": "Add opening hours."}],
)
print(next_response.output_text)

Kompaktowanie przy użyciu poprzedniego identyfikatora odpowiedzi

Można również skompresować, używając poprzedniego identyfikatora odpowiedzi.

initial_response = client.responses.create(
  model="MODEL_NAME",
  input="What is the size of France?"
)

compacted_response = client.responses.compact(
  model="MODEL_NAME",
  previous_response_id=initial_response.id
)

follow_up_response = client.responses.create(
  model="MODEL_NAME",
  input=[
    *compacted_response.output,
    {"role": "user", "content": "What is the capital?"}
  ]
)
print(follow_up_response.output_text)

Kompaktowanie po stronie serwera

Można także użyć kompaktowania po stronie serwera bezpośrednio w odpowiedziach (POST /responses lub client.responses.create) poprzez ustawienie context_management, używając compact_threshold.

  • Gdy liczba tokenów wyjściowych przekroczy skonfigurowany próg, interfejs API odpowiedzi automatycznie uruchamia kompaktowanie.
  • W tym trybie nie trzeba wywoływać /responses/compact oddzielnie.
  • Odpowiedź zawiera zaszyfrowany element kompaktowania.
  • Kompaktowanie po stronie serwera będzie działać po ustawieniu store=false w żądaniach utworzenia odpowiedzi.

Element kompaktowania przenosi dalej niezbędny poprzedni stan i rozumowanie w kolejnym etapie, używając mniej tokenów. Jest nieprzezroczyste i nie ma być czytelne dla człowieka.

Jeśli używasz bezstanowego łańcucha tablic wejściowych, dołącz elementy wyjściowe jak zwykle. Jeśli używasz previous_response_id, przekaż tylko nowy komunikat użytkownika przy każdej iteracji. W obu wzorcach element kompaktowania przenosi kontekst wymagany do następnego okna.

Wskazówka

Po dołączeniu elementów wyjściowych do poprzednich elementów wejściowych można usunąć elementy, które pojawiły się przed najnowszym elementem kompaktowania, aby zachować mniejsze żądania i zmniejszyć opóźnienie długiego ogona. Ostatni element kompresji niesie ze sobą niezbędny kontekst do kontynuowania rozmowy. Jeśli używasz previous_response_id łączenia, nie należy przycinać ręcznie.

Flow

  1. Zadzwoń responses jak zwykle. Dodaj context_management z compact_threshold aby włączyć kompaktowanie po stronie serwera.
  2. Jeśli dane wyjściowe przekroczą próg, usługa wyzwala kompaktowanie, emituje element kompaktowania w strumieniu wyjściowym i czyści kontekst przed kontynuowaniem wnioskowania.
  3. Kontynuuj konwersację przy użyciu jednego z następujących wzorców:
    1. Bezstanowe tworzenie łańcuchów tablic wejściowych: dołączanie elementów wyjściowych, w tym elementów kompaktowania, do następnej tablicy wejściowej.
    2. previous_response_id chaining: przekaż tylko nowy komunikat użytkownika na każdym etapie i przekazuj najnowszy identyfikator odpowiedzi na kolejny etap.

Przykład

conversation = [
  {
    "type": "message",
    "role": "user",
    "content": "Let's begin a long coding task.",
  }
]

while keep_going:
  response = client.responses.create(
    model="MODEL_NAME",
    input=conversation,
    store=False,
    context_management=[{"type": "compaction", "compact_threshold": 200000}],
  )

  conversation.append(
    {
      "type": "message",
       "role": "user",
      "content": get_next_user_input(),
    }
  )

Transmisja strumieniowa

Przesyłaj strumieniowo odpowiedź w miarę jego generowania, ustawiając wartość stream=true. Usługa emituje zdarzenia przyrostowe, które można wykorzystać do wyświetlania wyniku token po tokenie.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

stream = client.responses.create(
    model="MODEL_NAME",
    input="Summarize Azure OpenAI Responses API in one sentence.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")

Podczas strumieniowania, jeśli w jego trakcie wystąpi błąd, system podejmuje wewnętrzne próby ponowienia, aby go usunąć. Jeśli żądanie nadal kończy się niepowodzeniem, usługa napotka nieodwracalny błąd. W takich przypadkach kod odpowiedzi HTTP wynosi 200 (sukces), ale zdarzenie błędu w strumieniu zawiera szczegółowe informacje o błędach występujących w trakcie strumieniowania.

Serwer zwraca następujące typy błędów:

Typ błędu Można przetłumaczyć jako
server_error Kod zwrotny 500
too_many_requests Kod zwrotny 429
forbidden Kod zwrotny 403
user_error Kod zwrotny 400

Przykładowe zdarzenie błędu:

{
  "type": "error",
  "error": {
    "type": "too_many_requests",
    "code": "no_capacity",
    "headers": {
      "skip-error-remapping": "true"
    },
    "message": "The system is currently experiencing high demand and cannot process your request. Your request exceeds the maximum usage size allowed during peak load. For improved capacity reliability, consider switching to Provisioned Throughput.",
    "param": null
  }
}

Aplikacje powinny wykrywać te błędy i bezpiecznie zatrzymywać lub ponownie uruchamiać przesyłanie strumieniowe. Nie są naliczane opłaty za tokeny generowane podczas nieudanych odpowiedzi przesyłania strumieniowego.

Dane wyjściowe ze strukturą

Użyj ustrukturyzowanych danych wyjściowych, aby wykonać odpowiedź zgodnie ze schematem JSON. W żądaniu do Responses API zdefiniuj schemat w text.format. Chat Completions używa zamiast tego response_format. Przykłady SDK i interfejsu REST, obsługiwane ograniczenia schematu oraz ograniczenia znajdziesz w sekcji Ustrukturyzowane dane wyjściowe.

Wywoływanie funkcji

API Responses obsługuje wywołania funkcji.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)

tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_weather":
        args = json.loads(item.arguments)
        weather = {"location": args["location"], "temperature": "70 F"}
        tool_outputs.append(
            {
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(weather),
            }
        )

final_response = client.responses.create(
    model="MODEL_NAME",
    previous_response_id=response.id,
    input=tool_outputs,
)

print(final_response.output_text)

Obsługa barier zabezpieczających i filtrowania zawartości

Zastosuj zabezpieczenia (filtry zawartości) na poziomie wdrożenia. Każdy skonfigurowany mechanizm kontroli ocenia obsługiwaną zawartość i punkty interwencji: filtry podstawowych zagrożeń oceniają dane wejściowe i wyjściowe, wykrywanie ataków na prompt użytkownika ocenia dane wejściowe użytkownika, a wykrywanie ataków na dokument ocenia zawartość dokumentu po włączeniu. Skonfiguruj zabezpieczenia oddzielnie. Aby uzyskać więcej informacji, zobacz Konfigurowanie poręczy i kontrolek. W tej sekcji pokazano, jak wykrywać i obsługiwać wyniki działania mechanizmu guardrails podczas wywoływania interfejsu API Responses.

Interfejs API Responses prezentuje wyniki mechanizmów zabezpieczających inaczej niż Chat Completions. Zamiast pól prompt_filter_results i content_filter_results, które zwracają uzupełnienia czatu, obiekt odpowiedzi zawiera tablicę content_filters na najwyższym poziomie. Każdy wpis opisuje jeden wynik filtru.

Pole Opis
blocked Czy zawartość została zablokowana.
source_type Czy wynik dotyczy prompt (danych wejściowych) czy completion (danych wyjściowych).
content_filter_results Wyniki kategorii, takie jak hate, sexual, violence i self_harm, z poziomami ważności, oraz opcjonalne kategorie, takie jak jailbreak, indirect_attack, protected_material_text i protected_material_code.
content_filter_offsets Przesunięcia znaków, do których odnosi się wynik.

Uwaga

Tablica content_filters jest rozszerzeniem Microsoft Foundry, które nie jest częścią podstawowego schematu odpowiedzi OpenAI, więc zestawy SDK nie uwidaczniają dla niej właściwości wpisanej. Odczytaj je jako nieprzetworzone lub dodatkowe pole, jak pokazano w poniższych przykładach.

Wykrywanie zablokowanych danych wejściowych

Gdy zabezpieczenia blokują dane wejściowe, interfejs API zwraca błąd HTTP 400 z kodem content_filter. Przechwyć ten błąd, aby we właściwy sposób obsłużyć zablokowane polecenia.

import os
from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)

# A blocked prompt raises BadRequestError with the code "content_filter"
try:
    response = client.responses.create(
        model="MODEL_NAME",
        input="This is a test."
    )
    print(response.output_text)
except BadRequestError as error:
    if error.code == "content_filter":
        print("The prompt was blocked by a guardrail.")
    else:
        raise

Odczytywanie adnotacji zabezpieczających

Gdy żądanie zakończy się pomyślnie, odczytaj z odpowiedzi tablicę content_filters, aby sprawdzić wyniki zabezpieczeń dla danych wejściowych i wyjściowych.

W trybie adnotacji skonfigurowane kontrolki mogą zgłaszać poziom ważności lub wyniki wykrywania bez ich wymuszania. Odpowiadające wartości blocked i filtered pozostają false. Tryb adnotacji dla czterech kategorii podstawowych szkód wymaga zatwierdzenia zmodyfikowanych Guardrails.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
)
response = client.responses.create(
    model="MODEL_NAME",
    input="This is a test."
)

# content_filters is an Azure extension, so read it from model_extra
content_filters = response.model_extra.get("content_filters", [])
for result in content_filters:
    print(f"Source: {result['source_type']}, Blocked: {result['blocked']}")

Aby dowiedzieć się więcej o kategoriach zabezpieczeń i poziomach ważności, zobacz Omówienie zabezpieczeń oraz Praca z adnotacjami.

Interpreter kodu

Narzędzie interpretera kodu umożliwia modelom pisanie i wykonywanie kodu Python w bezpiecznym środowisku piaskownicy (sandbox). Obsługuje szereg zaawansowanych zadań, w tym:

  • Przetwarzanie plików o różnych formatach danych i strukturach
  • Generowanie plików zawierających dane i wizualizacje (na przykład grafy)
  • Iteracyjne pisanie i uruchamianie kodu w celu rozwiązania problemów — modele mogą debugować i ponawiać próbę kodu do momentu pomyślnego
  • Ulepszanie rozumowania wizualnego w obsługiwanych modelach (na przykład o3, o4-mini) przez włączenie przekształceń obrazów, takich jak przycinanie, powiększanie i obracanie
  • To narzędzie jest szczególnie przydatne w scenariuszach obejmujących analizę danych, obliczenia matematyczne i generowanie kodu.
curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
        "model": "MODEL_NAME",
        "tools": [
            { "type": "code_interpreter", "container": {"type": "auto"} }
        ],
        "instructions": "You are a personal math tutor. When asked a math question, write and run code using the python tool to answer the question.",
        "input": "I need to solve the equation 3x + 11 = 14. Can you help me?"
    }'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    instructions="You are a math tutor. Write and run Python code to solve math problems.",
    input="Solve 3x + 11 = 14."
)

print(response.output_text)

Containers

Ważne

Interpreter kodu ma dodatkowe opłaty wykraczające poza opłaty oparte na tokenach dla użycia usługi Azure OpenAI. Jeśli interfejs API odpowiedzi wywołuje interpreter kodu jednocześnie w dwóch różnych wątkach, tworzone są dwie sesje interpretera kodu. Każda sesja wiąże się z opłatami za minutę, a minimalna opłata wynosi pięć minut. Sesja pozostaje aktywna, o ile uzyskujesz dostęp do kontenera w ciągu 20-minutowego limitu czasu bezczynności.

Narzędzie Interpreter kodu wymaga kontenera — w pełni odizolowanej maszyny wirtualnej, na której model może wykonywać kod w Pythonie. Kontenery mogą zawierać przekazane pliki lub pliki wygenerowane podczas wykonywania.

Aby utworzyć kontener, określ "container": { "type": "auto", "file_ids": ["file-1", "file-2"] } w konfiguracji narzędzia podczas tworzenia nowego obiektu Response. Spowoduje to automatyczne utworzenie nowego kontenera lub ponowne użycie aktywnego kontenera z wcześniejszego wywołania `code_interpreter_call` w kontekście modelu. Element code_interpreter_call w danych wyjściowych interfejsu API będzie zawierać wygenerowane container_id. Ten kontener wygasa, jeśli nie jest używany przez 20 minut.

Obowiązują następujące limity plików:

  • Żądanie może zawierać maksymalnie 50 identyfikatorów plików.
  • Kontener może przechowywać łącznie do 1000 plików, w tym pliki wejściowe i pliki generowane przez interpreter kodu.

Dane wejściowe i wyjściowe pliku

Podczas uruchamiania interpretera kodu model może utworzyć własne pliki. Jeśli na przykład zostanie poproszony o utworzenie wykresu lub pliku CSV, utworzy te elementy bezpośrednio w twoim kontenerze. Przytacza te pliki w adnotacjach kolejnej wiadomości.

Wszystkie pliki w danych wejściowych modelu są automatycznie przekazywane do kontenera. Nie trzeba ręcznie przekazywać go do kontenera.

Obsługiwane pliki

Format pliku typ MIME
.c tekst/x-c
.cs text/x-csharp
.cpp text/x-c++
.csv tekst/csv
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html tekst/html
.java text/x-java
.json application/json
.md tekst/markdown
.pdf aplikacja/plik PDF
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb tekst/x-ruby
.tex text/x-tex
.txt tekst/zwykły
.css tekst/css
.js text/JavaScript
.sh application/x-sh
.ts application/TypeScript
.csv aplikacja/csv
.jpeg image/jpeg
.jpg image/jpeg
.gif obraz/gif
.pkl application/octet-stream
.png image/png
.tar aplikacja/x-tar
.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xml application/xml lub "text/xml"
.zip aplikacja/zip

Wyświetlanie listy elementów wejściowych

Pobierz elementy wejściowe, które zostały przesłane w odpowiedzi. Jest to przydatne do sprawdzania pełnego kontekstu konwersacji, w tym wszystkich elementów dodanych przez model (na przykład wywołań funkcji lub elementów kompaktowania).

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

items = client.responses.input_items.list("<response_id>")
print(items.model_dump_json(indent=2))

Przykładowa odpowiedź

{
  "object": "list",
  "data": [
    {
      "id": "msg_...",
      "type": "message",
      "role": "user",
      "content": [{"type": "input_text", "text": "This is a test."}]
    }
  ]
}

Dane wejściowe obrazu

Modele obsługujące analizę obrazu mogą interpretować obrazy razem z tekstem. Mogą rozpoznawać obiekty, kształty, kolory i tekstury oraz odczytywać tekst zawarty na obrazie, z zastrzeżeniem ograniczeń wymienionych w dalszej części tego artykułu.

Obraz można podać jako dane wejściowe żądania w dowolny z następujących sposobów:

  • W pełni kwalifikowany adres URL do pliku obrazu
  • URI danych zakodowany w Base64
  • Identyfikator pliku utworzony za pomocą interfejsu API plików

Adres URL obrazu

Odwołuj się do obrazu hostowanego pod publicznym adresem URL. Model pobiera obraz i dołącza go jako część zawartości wejściowej.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": "<image_url>"}
            ]
        }
    ]
)

print(response.output_text)

Obraz zakodowany w formacie Base64

Wyślij obraz bezpośrednio, kodując jego bajty jako URI danych base64. Użyj tego wzorca, gdy obraz nie jest hostowany pod publicznym adresem URL lub gdy chcesz uniknąć dodatkowego pobierania sieci.

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("path_to_your_image.jpg", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "image_url": f"data:image/jpeg;base64,{base64_image}"}
            ]
        }
    ]
)

print(response.output_text)

Identyfikator pliku

Przekaż obraz za pomocą interfejsu API plików przy użyciu polecenia purpose="assistants", a następnie odwołaj się do zwróconego identyfikatora pliku w żądaniu. Takie podejście jest przydatne, gdy chcesz ponownie użyć tego samego obrazu w wielu żądaniach bez ponownego wysłania bajtów.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

def create_file(file_path):
    with open(file_path, "rb") as file_content:
        result = client.files.create(
            file=file_content,
            purpose="assistants",
        )
        return result.id

file_id = create_file("path_to_your_image.jpg")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this image?"},
                {"type": "input_image", "file_id": file_id},
            ],
        }
    ],
)

print(response.output_text)

Wymagania dotyczące danych wejściowych obrazów

W poniższej tabeli wymieniono obsługiwane typy plików dla danych wejściowych obrazu.

Typ pliku typ MIME
PNG image/png
JPEG image/jpeg
WebP image/webp
Nieanimowany GIF image/gif

W jednym żądaniu można uwzględnić maksymalnie 50 obrazów. Każdy pojedynczy plik obrazu musi mieć rozmiar poniżej 512 MB, a łączny rozmiar monitu, w tym wszystkie obrazy w żądaniu, również musi wynosić poniżej 512 MB.

Obrazy muszą spełniać następujące dodatkowe wymagania:

  • Obraz musi być odpowiedni dla monitu; model nie jest przeznaczony dla niepowiązanej zawartości wizualnej.
  • Obrazy nie powinny zawierać szkodliwej ani poufnej zawartości naruszającej zasady zawartości.
  • Pliki obrazów nie mogą być uszkodzone ani nieczytelne. Jeśli model nie może przetworzyć obrazu, żądanie zakończy się niepowodzeniem.

Wybieranie poziomu szczegółów obrazu

Użyj właściwości detail we fragmencie zawartości input_image, aby określić, jak model przetwarza obraz. Niższy poziom szczegółowości zużywa mniej tokenów i działa szybciej, natomiast wyższy poziom szczegółowości zużywa więcej tokenów, ale pozwala modelowi wychwytywać drobniejsze cechy.

{
  "type": "input_image",
  "image_url": "<image_url>",
  "detail": "high"
}

W poniższej tabeli opisano każdy poziom szczegółów.

Poziom podsumowania Opis
low Model używa wersji obrazu o niższej rozdzielczości. Ta opcja używa najmniejszych tokenów i generuje najszybszą odpowiedź, ale model może przegapić szczegółowe informacje.
high Model używa wersji obrazu o wyższej rozdzielczości. Ta opcja przechwytuje bardziej szczegółowe informacje, ale używa większej liczby tokenów i trwa dłużej.
auto Domyślnie. Model wybiera odpowiedni poziom szczegółów na podstawie obrazu i monitu.

Ograniczenia wprowadzania obrazów

Modele z obsługą przetwarzania obrazów mają następujące ograniczenia:

  • Obrazy medyczne: Model nie jest odpowiedni do interpretacji wyspecjalizowanych obrazów medycznych, takich jak skany CT i nie powinien być używany do porad medycznych.
  • Tekst inny niż angielski: model może nie działać optymalnie podczas obsługi obrazów zawierających tekst w alfabetach innych niż łacińskich, takich jak japoński lub koreański.
  • Mały tekst: powiększanie tekstu na obrazie w celu zwiększenia czytelności, ale unikaj przycinania ważnych szczegółów.
  • Rotacja: model może źle interpretować obracany lub do góry nogami tekst i obrazy.
  • Elementy wizualne: model może zmagać się z grafami lub tekstami, w których kolory lub style — takie jak stałe, kreskowane lub kropkowane — różnią się.
  • Rozumowanie przestrzenne: model ma trudności z zadaniami wymagającymi dokładnej lokalizacji przestrzennej, takich jak identyfikowanie pozycji szachowych.
  • Dokładność: w niektórych przypadkach model może generować niepoprawne opisy lub podpisy.
  • Kształt obrazu: Ten model ma trudności z obrazów panoramicznych i z efektem rybiego oka.
  • Metadane i zmiana rozmiaru: model nie przetwarza oryginalnych nazw plików ani metadanych, a obrazy są zmieniane przed analizą, co wpływa na ich oryginalne wymiary.
  • Liczenie: model może dać przybliżone liczby obiektów na obrazach.
  • CAPTCHAs: Ze względów bezpieczeństwa system jest przeznaczony do blokowania przesyłania capTCHAs.

Dane wejściowe pliku

Modele z możliwościami przetwarzania obrazów obsługują dane wejściowe w formacie PDF. Plik PDF można udostępnić na dowolny z następujących sposobów:

  • Dane zakodowane w Base64
  • Identyfikator pliku utworzony za pomocą interfejsu API plików
  • Adres URL pliku zewnętrznego (file_url)

Aby ułatwić modelom interpretowanie zawartości PDF, kontekst modelu zawiera zarówno wyodrębniony tekst, jak i obraz każdej strony. Ta funkcja jest przydatna, gdy kluczowe informacje są przekazywane za pośrednictwem diagramów lub zawartości nietekstowej.

Uwaga

  • Cały wyodrębniony tekst i obrazy są umieszczane w kontekście modelu. Upewnij się, że rozumiesz wpływ cen i użycia tokenów na używanie plików PDF jako danych wejściowych.
  • W jednym żądaniu interfejsu API można dołączyć więcej niż jeden plik, ale każdy plik musi mieć wartość poniżej 50 MB. Łączny limit dla wszystkich plików w żądaniu wynosi 50 MB.
  • Tylko modele, które obsługują zarówno dane wejściowe tekstu, jak i obrazów, mogą akceptować pliki PDF jako dane wejściowe.
  • Obsługa purposeuser_data nie jest obecnie dostępna. Jako tymczasowe obejście należy ustawić cel na assistants.

Konwertowanie formatu PDF na format Base64 i analizowanie

Wyślij plik PDF bezpośrednio, kodując jego bajty jako URI danych w formacie base64. Model odbiera wyodrębniony tekst i renderowany obraz każdej strony.

import base64
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

with open("PDF-FILE-NAME.pdf", "rb") as f:
    base64_string = base64.b64encode(f.read()).decode("utf-8")

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "PDF-FILE-NAME.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}",
                },
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

Przekazywanie plików PDF i analizowanie

Przekaż plik PDF za pomocą polecenia purpose="assistants". purpose z user_data nie jest obecnie obsługiwany.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

file = client.files.create(
    file=open("nucleus_sampling.pdf", "rb"),
    purpose="assistants"
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_file", "file_id": file.id},
                {"type": "input_text", "text": "Summarize this PDF."},
            ],
        },
    ]
)

print(response.output_text)

Analizowanie pliku PDF z zewnętrznego adresu URL pliku

Odwołuj się do pliku PDF hostowanego pod publicznie dostępnym adresem URL przy użyciu file_url właściwości input_file elementu zawartości. Nie musisz najpierw pobierać, kodować ani przesyłać pliku.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Analyze the letter and provide a summary of the key points.",
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.berkshirehathaway.com/letters/2024ltr.pdf",
                },
            ],
        },
    ]
)

print(response.output_text)

Używanie zdalnych serwerów MCP

Możliwości modelu można rozszerzyć, łącząc go z narzędziami hostowanymi na zdalnych serwerach protokołu KONTEKSTU modelu (MCP). Te serwery są obsługiwane przez deweloperów i organizacje i udostępniają narzędzia, które są dostępne dla klientów kompatybilnych z MCP, takich jak API odpowiedzi.

Model Context Protocol (MCP) to otwarty standard, który definiuje sposób, w jaki aplikacje udostępniają narzędzia i dane kontekstowe dużym modelom językowym (LLMs). Umożliwia spójną, skalowalną integrację narzędzi zewnętrznych z przepływami pracy modelu.

W poniższym przykładzie pokazano, jak używać zdalnego serwera MCP do wykonywania zapytań dotyczących informacji o repozytorium interfejsu API REST Azure. Model pobiera i analizuje zawartość repozytorium w czasie rzeczywistym.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    input="What transport protocols are supported in the 2025-03-26 version of the MCP spec?"
)

print(response.output_text)

Narzędzie MCP działa tylko w interfejsie API odpowiedzi i jest dostępne we wszystkich nowszych modelach (gpt-4o, gpt-4.1 i naszych modelach rozumowania). W przypadku korzystania z narzędzia MCP płacisz tylko za tokeny używane podczas importowania definicji narzędzi lub wykonywania wywołań narzędzi — nie są naliczane żadne dodatkowe opłaty.

Zatwierdzenia

Domyślnie interfejs API odpowiedzi wymaga jawnego zatwierdzenia przed udostępnieniem jakichkolwiek danych zdalnemu serwerowi MCP. Ten krok zatwierdzania pomaga zapewnić przejrzystość i zapewnia kontrolę nad tym, jakie informacje są wysyłane zewnętrznie.

Zalecamy przejrzenie wszystkich danych udostępnianych zdalnym serwerom MCP i opcjonalne rejestrowanie ich na potrzeby inspekcji.

Gdy wymagane jest zatwierdzenie, model zwraca mcp_approval_request element w danych wyjściowych odpowiedzi. Ten obiekt zawiera szczegóły oczekującego żądania i umożliwia inspekcję lub modyfikowanie danych przed kontynuowaniem.

{
  "id": "mcpr_682bd9cd428c8198b170dc6b549d66fc016e86a03f4cc828",
  "type": "mcp_approval_request",
  "arguments": {},
  "name": "fetch_azure_rest_api_docs",
  "server_label": "github"
}

Aby kontynuować zdalne wywołanie MCP, należy odpowiedzieć na żądanie zatwierdzenia, tworząc nowy obiekt odpowiedzi zawierający element mcp_approval_response. Ten obiekt potwierdza zamiar umożliwienia modelowi wysyłania określonych danych do zdalnego serwera MCP.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "require_approval": "never"
        }
    ],
    previous_response_id="<previous_response_id>",
    input=[
        {
            "type": "mcp_approval_response",
            "approve": True,
            "approval_request_id": "<approval_request_id>"
        }
    ]
)

print(response.output_text)

Uwierzytelniania

Ważne

  • Klient MCP w interfejsie API odpowiedzi wymaga protokołu TLS 1.2 lub nowszego.
  • Mutual TLS (mTLS) nie jest obecnie obsługiwany.
  • Tagi usług Azure nie są obecnie obsługiwane dla ruchu klienta MCP.

W przeciwieństwie do serwera GitHub MCP większość zdalnych serwerów MCP wymaga uwierzytelniania. Narzędzie MCP w interfejsie API odpowiedzi obsługuje nagłówki niestandardowe, co umożliwia bezpieczne łączenie się z tymi serwerami przy użyciu wymaganego schematu uwierzytelniania.

Możesz określić nagłówki, takie jak klucze interfejsu API, tokeny dostępu OAuth lub inne poświadczenia bezpośrednio w swoim żądaniu. Najczęściej używany nagłówek to nagłówek Authorization.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="What is this repo in 100 words?",
    tools=[
        {
            "type": "mcp",
            "server_label": "github",
            "server_url": "https://contoso.com/Azure/azure-rest-api-specs",
            "headers": {"Authorization": "Bearer $YOUR_MCP_TOKEN"}
        }
    ]
)

print(response.output_text)

Zadania w tle

Tryb w tle umożliwia asynchroniczne wykonywanie długotrwałych zadań przy użyciu modeli rozumowania, takich jak o3 i o1-pro. Jest to przydatne w przypadku złożonych zadań, które mogą potrwać kilka minut (na przykład agentów w stylu Codex lub Deep Research). Po wysłaniu żądania z użyciem "background": true zadanie jest przetwarzane asynchronicznie, a następnie sprawdzasz jego stan.

Uruchamianie zadania w tle

Ustaw background=true w żądaniu, aby dodać zadanie do kolejki. Usługa zwraca natychmiast identyfikator odpowiedzi i queued stan — użyj tego identyfikatora, aby sondować, przesyłać strumieniowo lub anulować zadanie.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True
)

print(response.status)

Sonduj pod kątem ukończenia

Kontynuuj sondowanie, gdy stan to queued lub in_progress. Gdy odpowiedź osiągnie stan terminalu, jest ona dostępna do pobierania.

from time import sleep

while response.status in {"queued", "in_progress"}:
    print(f"Current status: {response.status}")
    sleep(2)
    response = client.responses.retrieve(response.id)

print(f"Final status: {response.status}\nOutput:\n{response.output_text}")

Anulowanie zadania w tle

Anuluj trwające zadanie w tle za pomocą punktu końcowego cancel. Anulowanie jest idempotentne — kolejne wywołania zwracają końcowy obiekt odpowiedzi.

response = client.responses.cancel("<response_id>")
print(response.status)

Aby strumieniować odpowiedź w tle, ustaw zarówno background, jak i stream na true. Ten wzorzec umożliwia wznowienie przesyłania strumieniowego, jeśli połączenie spadnie. Śledź swoją pozycję za pomocą sequence_number z każdego zdarzenia.

stream = client.responses.create(
    model="MODEL_NAME",
    input="Write me a very long story.",
    background=True,
    stream=True,
)

cursor = None
for event in stream:
    print(event)
    cursor = event["sequence_number"]

Odpowiedzi w tle mają obecnie większe opóźnienie od pierwszego tokenu niż odpowiedzi synchroniczne. W toku wprowadzono ulepszenia w celu zmniejszenia tej luki.

Ograniczenia

  • Tryb tła wymaga store=true. Żądania bezstanowe nie są obsługiwane.
  • Przesyłanie strumieniowe można wznowić tylko wtedy, gdy oryginalne żądanie zawierało element stream=true.
  • Aby anulować synchroniczną odpowiedź, zakończ połączenie bezpośrednio.

Wznawianie przesyłania strumieniowego z określonego punktu

Jeśli połączenie strumieniowe zostanie przerwane, możesz wznowić od znanego zdarzenia, przekazując stream=true wraz z starting_after=<sequence_number> w odpowiedzi GET. Usługa odtwarza zdarzenia emitowane po tym numerze sekwencji.

curl -N -X GET "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses/<response_id>?stream=true&starting_after=42" \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

Szyfrowane rozumowanie

Jeśli używasz modelu rozumowania z interfejsem Responses API w trybie bezstanowym (store=false), aplikacja dostarcza kontekst dla każdego kolejnego żądania. Wcześniejsze wiadomości zawierają historię konwersacji, ale nie zawierają wewnętrznego rozumowania modelu. Zaszyfrowany element zawierający tok rozumowania umożliwia przenoszenie zgodnego kontekstu rozumowania do późniejszego żądania bez uwidaczniania tego rozumowania jako czytelnego tekstu w aplikacji.

Dlaczego warto używać szyfrowanego wnioskowania?

Użyj szyfrowanego rozumowania, gdy aplikacja zarządza stanem konwersacji i musi kontynuować wieloetapowy przepływ pracy rozumowania. Na przykład użytkownik może zadać pytanie uzupełniające lub model może wywołać narzędzie, a następnie kontynuować po otrzymaniu wyniku.

Przekazywanie wcześniejszych komunikatów nie przekazuje samego kontekstu rozumowania modelu z poprzedniej tury. Zaszyfrowany element rozumowania przenosi ten kontekst do przodu, zachowując zawartość nieczytelną dla aplikacji.

Korzystanie

  1. Ustaw wartość store=false. Aby jawnie zażądać zaszyfrowanego rozumowania, dodaj reasoning.encrypted_content do parametru include , jak pokazano w poniższych przykładach.
  2. Zachowaj wszystkie zwrócone elementy wyjściowe w ich oryginalnej kolejności, w tym elementy rozumowania z właściwością encrypted_content .
  3. W następnym wywołaniu uwzględnij te elementy z innymi odpowiednimi elementami rozmowy w elemencie input i nadal ustawiaj store=false. Nie należy używać previous_response_id w przypadku niezapisanej odpowiedzi.

Odpowiedzi bezstanowe domyślnie zwracają zaszyfrowaną zawartość; include parametr pozostaje obsługiwany pod kątem zgodności. Powtórzenie elementu sprawia, że jest dostępne zgodne rozumowanie, ale rozumowanie używane przez model zależy od obsługiwanego trybu kontekstu rozumowania. Aby uzyskać szczegółowe informacje, zobacz Zachowywanie rozumowania między wywołaniami.

W trybie bezstanowym zaszyfrowany element reasoning jest zwracany do aplikacji. Aplikacja jest odpowiedzialna za bezpieczne przechowywanie jej i przekazywanie jej z powrotem przy kolejnym żądaniu. Wybierz lokalizację magazynu po stronie aplikacji, która spełnia wymagania dotyczące zabezpieczeń i cyklu życia.

W poniższych próbkach użyto uwierzytelniania za pomocą klucza interfejsu API. Przykłady w Pythonie korzystają z biblioteki klienckiej OpenAI. Inne przykłady bezpośrednio wywołują punkt końcowy REST Responses i zachowują pełne elementy wyjściowe jako dane JSON.

Zainstaluj zależności dla danego języka:

  • Python: zainstaluj klienta poleceniem pip install --upgrade openai.
  • C#: Użyj aplikacji konsolowej .NET 8 lub nowszej. Nie są wymagane żadne dodatkowe pakiety.
  • JavaScript: użyj Node.js 18 lub nowszy i zapisz każdy przykład jako plik .mjs. Nie są wymagane żadne dodatkowe pakiety.
  • Java: użyj zestawu JDK 17 lub nowszego i dodaj zależność Maven com.fasterxml.jackson.core:jackson-databind:2.22.4. Zapisz każdą próbkę pod nazwą pliku wyświetlaną na jego karcie.
  • REST: Uruchom przykłady programu PowerShell przy użyciu programu PowerShell 7 lub nowszego.

Ustaw następujące zmienne środowiskowe dla każdego języka:

  • AZURE_OPENAI_ENDPOINT: Punkt końcowy zasobu, taki jak https://YOUR-RESOURCE-NAME.openai.azure.com.
  • AZURE_OPENAI_API_KEY: Twój klucz API.
  • AZURE_OPENAI_DEPLOYMENT: nazwa obsługiwanego wdrożenia modelu rozumowania.

Oba przykłady sprawdzają zaszyfrowany element rozumowania i zgłaszają błąd, jeśli żaden nie zostanie zwrócony. Użyj konfiguracji wdrażania i rozumowania, która generuje elementy rozumowania dla przykładowych żądań.

Kontynuuj rozmowę bez zachowywania stanu

Ten przykład zachowuje zwrócone elementy na liście zarządzanej przez aplikację i przekazuje je do kolejnego żądania.

import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

# Application-managed state. This example keeps it in memory.
conversation = [
    {"role": "user", "content": "Explain the trade-offs of this design."}
]


def add_response_items(response):
    items = [item.model_dump(exclude_none=True) for item in response.output]

    if not any(
        item.get("type") == "reasoning" and item.get("encrypted_content")
        for item in items
    ):
        raise RuntimeError(
            "No encrypted reasoning item was returned. Check the deployment "
            "and the request's include parameter."
        )

    # Preserve the returned items, including encrypted reasoning.
    conversation.extend(items)


try:
    first = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(first)
    print("First answer:", first.output_text)

    conversation.append({
        "role": "user",
        "content": "Which trade-off matters most for reliability?",
    })

    second = client.responses.create(
        model=deployment,
        input=conversation,
        store=False,
        include=["reasoning.encrypted_content"],
    )
    add_response_items(second)
    print("Follow-up answer:", second.output_text)

except BadRequestError as exc:
    # Inspect the service error before deciding whether to restart.
    print(f"Request rejected: {exc}")
    raise

Przykład wyświetla pierwszą odpowiedź i odpowiedź uzupełniającą. Zachowuje wszystkie elementy wyjściowe, w tym zaszyfrowane rozumowanie, a nie tylko czytelną odpowiedź.

Lista conversation to miejsce, w którym aplikacja tego przykładu przechowuje elementy. Jest on przechowywany w pamięci i nie przetrwa ponownego uruchomienia procesu. Aplikacja, która musi zostać wznowiona później, musi wybrać i zabezpieczyć własne miejsce do przechowywania.

Kontynuuj po wywołaniu narzędzia

Ten przykład zachowuje elementy rozumowania i wywołania funkcji, wykonuje przykładową funkcję i wysyła wynik z powrotem przy użyciu zgodnego call_idelementu .

import json
import os

from openai import BadRequestError, OpenAI

client = OpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
)
deployment = os.environ["AZURE_OPENAI_DEPLOYMENT"]

tools = [{
    "type": "function",
    "name": "get_order_status",
    "description": "Look up the status of an example order.",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"}
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}]


def get_order_status(order_id):
    # Replace this example with your own trusted data source.
    if order_id == "A123":
        return {"order_id": order_id, "status": "Shipped"}
    return {"order_id": order_id, "status": "Not found"}


conversation = [{
    "role": "user",
    "content": "What is the status of order A123?",
}]


def create_response():
    return client.responses.create(
        model=deployment,
        input=conversation,
        tools=tools,
        store=False,
        include=["reasoning.encrypted_content"],
    )


try:
    # Bound the number of tool rounds.
    for _ in range(3):
        response = create_response()
        items = [item.model_dump(exclude_none=True) for item in response.output]

        if not any(
            item.get("type") == "reasoning" and item.get("encrypted_content")
            for item in items
        ):
            raise RuntimeError("No encrypted reasoning item was returned.")

        # Preserve returned items in order, including reasoning and tool calls.
        conversation.extend(items)

        calls = [
            item for item in response.output
            if item.type == "function_call"
        ]
        if not calls:
            print(response.output_text)
            break

        for call in calls:
            if call.name != "get_order_status":
                raise ValueError(f"Unexpected tool: {call.name}")

            arguments = json.loads(call.arguments)
            result = get_order_status(arguments["order_id"])

            conversation.append({
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
            })
    else:
        raise RuntimeError("The tool-call limit was reached.")

except BadRequestError as exc:
    print(f"Request rejected: {exc}")
    raise

Przykład wyświetla ostateczną odpowiedź modelu po przetworzeniu przykładowego statusu zamówienia. Funkcja używa przykładowych danych, a nie systemu zamówień na żywo. Pętla ogranicza liczbę żądań odpowiedzi od modelu do trzech i zgłasza błąd, jeśli model nadal prosi o narzędzia.

Zachowaj zaszyfrowane elementy wnioskowania bez zmian; nie próbuj odczytywać ani modyfikować ich zaszyfrowanej zawartości. Aby zapoznać się z definicjami funkcji i formatami wyników narzędzia, zobacz Wywoływanie funkcji.

Zagadnienia dotyczące trasowania

W przypadku kierowania przez Azure API Management zweryfikuj zaszyfrowane odtwarzanie rozumowania w skonfigurowanych zapleczach przed jego użyciem. Jeśli usługa zwróci invalid_encrypted_content, sprawdź błąd i routing zasobów przed podjęciem decyzji, czy ponownie uruchomić konwersację.

Zagadnienia dotyczące ochrony danych

Zaszyfrowane elementy rozumowania przenoszą nieprzezroczysty kontekst rozumowania między żądaniami. Nie opisują one sposobu szyfrowania przechowywanych danych przez usługę, które klucze chronią przechowywane prompty lub stan konwersacji lub gdzie aplikacja musi przechowywać zwrócone elementy.

Ustawienie store=false nie jest całkowitą gwarancją zerowego przechowywania w każdym procesie usługi. Aby uzyskać szczegółowe informacje o przechowywaniu po stronie usługi i monitorowaniu nadużyć, zobacz Dane, prywatność i zabezpieczenia dla Azure OpenAI.

Generowanie obrazu

Interfejs API odpowiedzi umożliwia generowanie obrazów w ramach konwersacji i wieloetapowych przepływów pracy. Obsługuje obrazy jako dane wejściowe i wyjściowe w ramach kontekstu oraz zawiera wbudowane narzędzia do generowania i edytowania obrazów.

W porównaniu z samodzielnym interfejsem API obrazów, interfejs Responses API oferuje dwie zalety:

  • Przesyłanie strumieniowe: wyświetlanie częściowych danych wyjściowych obrazu w trakcie generowania w celu zwiększenia widocznego opóźnienia.
  • Elastyczne dane wejściowe: akceptuj identyfikatory plików obrazów jako dane wejściowe oprócz nieprzetworzonych bajtów obrazu.

Uwaga

Narzędzie do generowania obrazów w Responses API jest obsługiwane przez modele z serii gpt-image-1, a wywoływać je można za pomocą wybranych zgodnych modeli czatu i wnioskowania. Aby zapoznać się z bieżącą listą obsługiwanych modeli aranżacji, zobacz sekcję Obsługiwane modele w dalszej części tego artykułu.

Narzędzie do generowania obrazów nie obsługuje obecnie trybu przesyłania strumieniowego. Aby strumieniować obrazy częściowe, wywołaj bezpośrednio interfejs API generowania obrazów, z pominięciem interfejsu Responses API.

Użyj interfejsu Responses API, aby tworzyć konwersacyjne środowiska pracy z obrazami za pomocą modeli GPT Image.

import base64
import os
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,
    default_headers={
        "x-ms-oai-image-generation-deployment": os.getenv("IMAGE_MODEL_NAME"),
        "api_version": "preview",
    },
)

response = client.responses.create(
    model="MODEL_NAME",
    input="Generate an image of a gray tabby cat hugging an otter with an orange scarf.",
    tools=[{"type": "image_generation"}],
)

image_data = [
    output.result
    for output in response.output
    if output.type == "image_generation_call"
]

if image_data:
    with open("otter.png", "wb") as f:
        f.write(base64.b64decode(image_data[0]))

Modele rozumowania

Aby zapoznać się z przykładami używania modeli rozumowania z interfejsem API odpowiedzi, zobacz przewodnik po modelach rozumowania.

Korzystanie z komputera

Funkcja korzystania z komputera w Playwright została przeniesiona do dedykowanego przewodnika po modelu korzystania z komputera.

Rozwiązywanie problemów

Dlaczego moja sesja interfejsu API została zakończona jako środek ostrożności?

W przypadku korzystania z modeli Astra, aby upewnić się, że agenci interpretują i postępują zgodnie z instrukcjami prawidłowo, mamy system, który zatrzymuje sesje w interfejsie API odpowiedzi, jeśli wykryje, że agent może nie interpretować instrukcji poprawnie w takich przypadkach, jak przesyłanie poufnych danych, uzyskiwanie dostępu do poufnych danych lub wprowadzanie destrukcyjnych zmian. Jeśli sesja została zakończona, nie musi to koniecznie oznaczać, że agent popełnił błąd, a jedynie, że warto przejrzeć jego działania, aby upewnić się, że prawidłowo zinterpretował i wykonał Twoje instrukcje.

Które żądania interfejsu API są monitorowane przez ten system?

Ten sam system opisany powyżej asynchronicznie monitoruje żądania kierowane do Astry w interfejsie Responses API. Interfejs API Chat Completions nie jest objęty skanowaniem przez ten konkretny system monitorujący. Zalecamy korzystanie z Responses API, aby zapewnić najwyższą wydajność i bezpieczeństwo w zastosowaniach agentowych.

Jak wykryć, że konwersacja została zakończona w interfejsie API przez ten system?

Gdy system bezpieczeństwa wykryje, że agent mógł w istotny sposób błędnie zinterpretować instrukcje, interfejs API zwraca kod adnotacji bezpieczeństwa misalignment-enforcement. W takim przypadku dana sesja nie może zostać wznowiona.

Co powinna zrobić moja aplikacja, jeśli taki przypadek zostanie wykryty?

Możesz rozważyć skonfigurowanie systemu, aby umożliwić komuś przejrzenie akcji, które agent podjął w takich konwersacjach, na przykład poprzez udostępnienie interfejsu użytkownika użytkownikowi końcowemu do przejrzenia. Po zatrzymaniu konwersacji z tego powodu w interfejsie API nie można go wznowić.

Rozwiązywanie typowych błędów interfejsu API

Skorzystaj z poniższych wskazówek, aby rozwiązać typowe błędy interfejsu API:

  • 401/403: Jeśli używasz Microsoft Entra ID, sprawdź, czy token ma określony zakres dla https://ai.azure.com/.default. Jeśli używasz klucza interfejsu API, upewnij się, że używasz poprawnego klucza dla zasobu.
  • 404: Potwierdź, że model jest zgodna z nazwą wdrożenia.

Powiązana zawartość

  • Ostatnia aktualizacja o