Azure Openai To Responses

Migrasi Aplikasi Python daripada Azure OpenAI Chat Completions ke Responses API

PANDUAN BERWIBAWA — IKUTI DENGAN TEPAT

Kemahiran ini memindahkan pangkalan kod Python yang menggunakan Azure OpenAI Chat Completions ke Responses API yang bersatu. Ikuti arahan ini dengan tepat. Jangan mengubah suai pemetaan parameter atau mencipta bentuk API baru.

Pencetus

Aktifkan kemahiran ini apabila pengguna ingin:

• Memindahkan aplikasi Python daripada Azure OpenAI Chat Completions ke Responses API
• Meningkatkan penggunaan SDK OpenAI Python ke bentuk API terkini dengan Azure OpenAI
• Menyediakan kod Python untuk model GPT-5 atau yang lebih baru yang memerlukan Responses di Azure
• Beralih dari AzureOpenAI/AsyncAzureOpenAI ke klien standard OpenAI/AsyncOpenAI dengan titik akhir v1
• Memperbaiki amaran deprecasi berkaitan konstruktor AzureOpenAI atau api_version

⚠️ Keserasian Model — PERIKSA DULU

Sebelum migrasi, sahkan penyebaran Azure OpenAI anda menyokong Responses API.

1. Ujian ringkas penyebaran anda (pantas)

import os
from openai import OpenAI

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

try:
    resp = client.responses.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        input="ping",
        max_output_tokens=50,
        store=False,
    )
    print(f"✅ Deployment supports Responses API: {resp.output_text}")
except Exception as e:
    print(f"❌ Deployment does NOT support Responses API: {e}")

Nota: max_output_tokens mempunyai minimum 16 di Azure OpenAI. Nilai di bawah 16 akan menghasilkan ralat 400. Gunakan 50+ untuk ujian ringkas.

Jika ini mengembalikan 404, model penyebaran tidak menyokong Responses lagi — semak rujukan di bawah atau lakukan penyebaran semula dengan model yang disokong.

2. Semak model tersedia di rantau anda (disyorkan)

Jalankan alat keserasian model terbina dalam untuk melihat apa yang tersedia dengan sokongan Responses API di rantau anda:

python migrate.py models --subscription YOUR_SUB_ID --location YOUR_REGION

Ini mengquery ARM Azure secara langsung dan menunjukkan matriks keserasian — model mana yang menyokong Responses, output berstruktur, alat, dan lain-lain. Gunakan --filter gpt-5.1,gpt-5.2 untuk mengehadkan hasil atau --json untuk skrip.

3. Rujukan lengkap sokongan model

• Query langsung: python migrate.py models (lihat di atas — khusus rantau, sentiasa terkini)
• Layari ketersediaan: Jadual ringkasan model dan ketersediaan rantau
• Mula cepat & panduan: https://aka.ms/openai/start

⚠️ Had model lama

AMARAN: Model lama (yang lebih tua daripada gpt-4.1) mungkin tidak menyokong semua ciri Responses API sepenuhnya.

Had yang diketahui dengan model lama:

• Parameter reasoning: Tidak disokong oleh banyak model bukan beralasan. Hanya migrasi reasoning jika sudah wujud dalam kod asal.
• Parameter seed: Tidak disokong langsung dalam Responses API — keluarkan dari semua permintaan.
• Output berstruktur melalui text.format: Model lama mungkin tidak menguatkuasakan skema JSON strict: true dengan stabil.
• Pengurusan alat: GPT-5+ menguruskan panggilan alat sebagai sebahagian daripada alasan dalaman. Model lama pada Responses masih berfungsi tetapi tiada integrasi mendalam ini.
• Had suhu: Apabila migrasi ke gpt-5, suhu mesti tidak dimasukkan atau ditetapkan kepada 1. Model lama tiada had sebegini.

Model beralasan siri O (o1, o3-mini, o3, o4-mini)

Model siri O mempunyai had parameter unik. Apabila migrasi aplikasi yang mensasarkan model siri O:

• temperature: Mesti 1 (atau tidak dimasukkan). Model siri O tidak menerima nilai lain.
• max_completion_tokens → max_output_tokens: Aplikasi yang menggunakan max_completion_tokens khusus Azure mesti bertukar ke max_output_tokens. Tetapkan nilai tinggi (4096+) kerana token beralasan dikira dalam had.
• reasoning_effort: Jika aplikasi menggunakan reasoning_effort (rendah/sederhana/tinggi), kekalkan — Responses API menyokong parameter ini untuk model siri O.
• Tingkah laku streaming: Model siri O mungkin menyimpan output sehingga alasan selesai sebelum mengeluarkan acara delta teks. Streaming masih berfungsi, tetapi response.output_text.delta pertama mungkin tiba lewat berbanding model GPT.
• top_p: Tidak disokong pada siri O — keluarkan jika ada.
• Penggunaan alat: Model siri O menyokong alat melalui Responses API sama seperti model GPT, tetapi kualiti pengurusan panggilan alat berbeza mengikut model.

Tindakan — nasihat model proaktif: Semasa fasa imbasan, periksa model yang dituju aplikasi (nama penyebaran, pembolehubah persekitaran, konfigurasi). Jika model lebih tua daripada gpt-4.1 (bukan gpt-4.1+), beritahu pengguna secara proaktif:

• Migrasi akan berfungsi untuk teks asas, chat, streaming, dan alat pada model semasa mereka.
• Model terbaru (gpt-5.1, gpt-5.2) menawarkan pengurusan alat lebih baik, penguatkuasaan output berstruktur, beralasan, dan ketersediaan merentas rantau.
• Mereka patut pertimbangkan untuk menaik taraf penyebaran apabila bersedia — ia tidak menghalang migrasi.

Jangan halang atau tolak migrasi berdasarkan versi model. Nasihat adalah untuk maklumat sahaja.

GitHub Models TIDAK menyokong Responses API

GitHub Models (models.github.ai, models.inference.ai.azure.com) tidak menyokong Responses API.

Jika pangkalan kod ada laluan kod GitHub Models (cari base_url yang menunjuk ke models.github.ai atau models.inference.ai.azure.com), buang sepenuhnya semasa migrasi. Responses API memerlukan Azure OpenAI, OpenAI, atau titik akhir tempatan yang serasi (contohnya, Ollama dengan sokongan Responses).

Tindakan semasa imbasan:

• Tandakan mana-mana laluan kod GitHub Models untuk dikeluarkan.

Migrasi Kerangka Kerja

Banyak aplikasi menggunakan kerangka kerja peringkat tinggi di atas OpenAI. Apabila memigrasi ini, perubahan API kerangka kerja sendiri — bukan hanya panggilan OpenAI asas.

Microsoft Agent Framework (MAF)

Periksa versi MAF anda dahulu — migrasi bergantung sama ada anda pada MAF 1.0.0+ atau beta/rc sebelum 1.0.0.

MAF 1.0.0+ (agent-framework-openai >= 1.0.0)

OpenAIChatClient sudah menggunakan Responses API — tiada migrasi diperlukan. Jika pangkalan kod menggunakan OpenAIChatCompletionClient warisan (yang menggunakan chat.completions.create), gantikan dengan OpenAIChatClient.

Untuk periksa versi anda: python -c "import agent_framework_openai; print(agent_framework_openai.__version__)"

MAF sebelum 1.0.0 (rilis beta/rc)

Pada MAF sebelum 1.0.0, OpenAIChatClient menggunakan Chat Completions. Tingkatkan ke agent-framework-openai>=1.0.0 di mana OpenAIChatClient menggunakan Responses API secara lalai.

Tiada perubahan lain diperlukan — API Agent dan alat kekal sama.

LangChain (langchain-openai)

Tambah use_responses_api=True ke ChatOpenAI(). Juga kemas kini akses respons daripada .content ke .text.

Untuk contoh kod lengkap sebelum/selepas, lihat cheat-sheet.md.

Panduan Migrasi Frontend

Responses API adalah perkara sisi pelayan. Migrasikan backend Python anda; kontrak HTTP frontend harus kekal tidak berubah kecuali backend anda hanya laluan nipis — dalam kes itu, pertimbangkan menggunakan bentuk permintaan Responses untuk menghapuskan lapisan terjemahan. Jika frontend memanggil OpenAI secara langsung dengan kunci sisi klien, alihkan panggilan itu ke backend terlebih dahulu.

Deprecation @microsoft/ai-chat-protocol

Pakej npm @microsoft/ai-chat-protocol sudah usang dan perlu digantikan dengan ndjson-readablestream. Jika anda menjumpainya di frontend:

1. Gantikan tag skrip CDN:

   <!-- Before -->
   <script src="https://cdn.jsdelivr.net/npm/@microsoft/ai-chat-protocol@.../dist/iife/index.js"></script>
   <!-- After -->
   <script src="https://cdn.jsdelivr.net/npm/ndjson-readablestream@1.0.7/dist/ndjson-readablestream.umd.js"></script>

2. Keluarkan instansiasi AIChatProtocolClient (new ChatProtocol.AIChatProtocolClient("/chat")).
3. Gantikan client.getStreamedCompletion(messages) dengan panggilan fetch() terus ke titik akhir streaming backend.
4. Gantikan for await (const response of result) dengan for await (const chunk of readNDJSONStream(response.body)).
5. Kemas kini akses sifat daripada response.delta.content / response.error ke chunk.delta.content / chunk.error.

Matlamat

• Senaraikan semua tapak panggilan Python yang menggunakan Chat Completions atau Completions warisan terhadap Azure OpenAI.
• Cadangkan pelan migrasi dan susunan untuk pangkalan kod Python.
• Buat suntingan selamat dan minimum untuk beralih ke Responses API.
• Kemas kini pemanggil untuk menggunakan skema output Responses; tiada pembungkus keserasian belakang.
• Jalankan ujian/lint; baiki kerosakan kecil yang diperkenalkan oleh migrasi.
• Sediakan set perubahan kecil yang boleh dikaji dan berikan ringkasan akhir dengan perbezaan (jangan komit).

Panduan Keselamatan

• Hanya ubah fail dalam ruang kerja git. Jangan tulis luar ruang kerja.
• Jangan simpan shim keserasian belakang; migrasi kod ke bentuk API baru.
• Jangan tinggalkan komen peralihan/tanda kubur atau fail sandaran.
• Kekalkan semantik streaming jika sebelum ini digunakan; jika tidak, guna bukan streaming.
• Minta kelulusan sebelum menjalankan arahan atau panggilan rangkaian jika dalam mod kelulusan.
• Jangan jalankan git add/git commit/git push; hasilkan suntingan pokok kerja sahaja.

Langkah 0: Migrasi Klien Azure OpenAI (Prasyarat)

Jika pangkalan kod menggunakan konstruktor AzureOpenAI atau AsyncAzureOpenAI, migrasi ke konstruktor standard OpenAI / AsyncOpenAI terlebih dahulu. Konstruktor khusus Azure ini sudah usang dalam openai>=1.108.1.

Mengapa laluan API v1?

Titik akhir baru /openai/v1 menggunakan klien standard OpenAI() dan bukan AzureOpenAI(), tidak memerlukan parameter api_version, dan berfungsi sama rata di OpenAI dan Azure OpenAI. Kod klien yang sama ini tahan masa depan — tiada pengurusan versi diperlukan.

Perubahan penting

Senarai semak pembersihan

• Keluarkan argumen api_version daripada konstruktor klien.
• Keluarkan pembolehubah persekitaran AZURE_OPENAI_VERSION / AZURE_OPENAI_API_VERSION dari .env, tetapan aplikasi, dan fail Bicep/infra.
• Namakan semula AZURE_OPENAI_CLIENT_ID → AZURE_CLIENT_ID dalam .env, tetapan aplikasi, Bicep/infra, dan fixtur ujian (konvensyen SDK Identiti Azure standard).
• Pastikan openai>=1.108.1 dalam requirements.txt atau pyproject.toml.

Migrasi pembolehubah persekitaran

Untuk contoh kod penyediaan klien (sync, async, EntraID, kunci API, berbilang penyewa), lihat cheat-sheet.md.

Langkah 1: Kenal Pasti Tapak Panggilan Warisan

Jalankan skrip detect_legacy.py untuk mencari semua tapak panggilan yang perlu dimigrasi:

python skills/azure-openai-to-responses/scripts/detect_legacy.py .

Atau jalankan carian ini secara manual — setiap padanan adalah sasaran migrasi:

# Panggilan API Legacy (perlu tulis semula)
rg "chat\.completions\.create"
rg "ChatCompletion\.create"
rg "Completion\.create"

# Pembina klien Azure yang telah usang (perlu gantikan)
rg "AzureOpenAI\("
rg "AsyncAzureOpenAI\("

# Corak akses bentuk respons (perlu kemas kini)
rg "choices\[0\]\.message\.content"
rg "choices\[0\]\.delta\.content"
rg "choices\[0\]\.message\.function_call"
rg "choices\[0\]\.message\.tool_calls"

# Definisi alat dalam format bertingkat lama (perlu ratakan)
rg '"function":\s*{\s*"name"'
rg "pydantic_function_tool"

# Keputusan alat dalam format lama (perlu tukar kepada function_call_output)
rg '"role":\s*"tool"'
rg '"tool_call_id"'

# Parameter yang telah usang (perlu keluarkan atau tukar nama)
rg "response_format"
rg "max_tokens\b"        # tukar nama kepada max_output_tokens
rg "['\"]seed['\"]"      # remove entirely

# Pembolehubah persekitaran yang telah usang (bersihkan)
rg "AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION"
rg "AZURE_OPENAI_CLIENT_ID"  # sepatutnya AZURE_CLIENT_ID

# Titik hujung Model GitHub (perlu keluarkan — API Respons tidak disokong)
rg "models\.github\.ai|models\.inference\.ai\.azure"

# Corak legacy tahap rangka kerja (perlu kemas kini)
rg "OpenAIChatCompletionClient"  # MAF 1.0.0+: gantikan dengan OpenAIChatClient
rg "ChatOpenAI\(" | grep -v "use_responses_api"  # LangChain: perlu use_responses_api=True

# Infrastruktur ujian (perlu kemas kini)
rg "ChatCompletionChunk|AsyncCompletions\.create" tests/
rg "_azure_ad_token_provider" tests/
rg "prompt_filter_results|content_filter_results" tests/
rg "choices\[0\]" tests/

# Akses badan ralat penapis kandungan (perlu kemas kini — struktur telah berubah)
rg 'innererror.*content_filter_result|error\.body\["innererror"\]'
rg "content_filter_result\[" # bentuk tunggal lama — sekarang content_filter_results (jamak) di dalam tatasusunan content_filters

# Panggilan HTTP mentah ke titik hujung Chat Completions (perlu kemas kini URL)
rg "/openai/deployments/.*/chat/completions"
rg "api-version="