azure-openai-to-responses

ย้ายแอป Python จาก Azure OpenAI Chat Completions ไปยัง Responses API

คำแนะนำอย่างเป็นทางการ — ทำตามอย่างเคร่งครัด

ทักษะนี้จะย้ายฐานโค้ด Python ที่ใช้ Azure OpenAI Chat Completions ไปยัง Responses API แบบรวมศูนย์ โปรดทำตามคำแนะนำเหล่านี้อย่างแม่นยำ หลีกเลี่ยงการปรับแม็ปพารามิเตอร์เองหรือคิดค้นรูปแบบ API ใหม่

ตัวจุดเริ่มต้น

เปิดใช้งานทักษะนี้เมื่อผู้ใช้ต้องการ:

ย้ายแอป Python จาก Azure OpenAI Chat Completions ไปยัง Responses API
อัพเกรดการใช้งาน Python OpenAI SDK ไปยังรูปแบบ API ล่าสุดกับ Azure OpenAI
เตรียมโค้ด Python สำหรับโมเดล GPT-5 หรือใหม่กว่าที่ต้องการ Responses บน Azure
เปลี่ยนจากไคลเอนต์ AzureOpenAI/AsyncAzureOpenAI เป็น OpenAI/AsyncOpenAI แบบมาตรฐานที่ใช้ปลายทาง v1
แก้ไขคำเตือนการเลิกใช้ที่เกี่ยวกับตัวสร้าง AzureOpenAI หรือ api_version

⚠️ ความเข้ากันได้ของโมเดล — ตรวจสอบก่อน

ก่อนย้าย ตรวจสอบให้แน่ใจว่า deployment Azure OpenAI ของคุณรองรับ Responses API

1. ทดสอบอย่างรวดเร็ว (เร็วที่สุด)

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

หมายเหตุ: บน Azure OpenAI max_output_tokens มีค่าขั้นต่ำ 16 ค่าที่ต่ำกว่า 16 จะส่งคืนข้อผิดพลาด 400 ใช้ค่า 50+ สำหรับการทดสอบแบบรวดเร็ว

หากส่งคืน 404 โมเดลใน deployment นี้ยังไม่รองรับ Responses — ตรวจสอบข้อมูลอ้างอิงด้านล่างหรือเปิดใช้งานใหม่ด้วยโมเดลที่รองรับ

2. ตรวจสอบโมเดลที่มีในภูมิภาคของคุณ (แนะนำ)

ใช้เครื่องมือรองรับโมเดลในตัวเพื่อดูว่ามีอะไรพร้อมใช้งานกับ Responses API ในภูมิภาคของคุณ:

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

เครื่องมือนี้เรียก Azure ARM สดและแสดงแมทริกซ์ความเข้ากันได้ — โมเดลใดรองรับ Responses, การส่งออกแบบมีโครงสร้าง, เครื่องมือ ฯลฯ ใช้ --filter gpt-5.1,gpt-5.2 เพื่อลดผลลัพธ์หรือ --json สำหรับสคริปต์

3. อ้างอิงการรองรับโมเดลเต็มรูปแบบ

การเรียกดูสด: python migrate.py models (ดูด้านบน — เฉพาะภูมิภาค, อัปเดตเสมอ)
เรียกดูความพร้อมใช้งาน: ตารางสรุปโมเดลและความพร้อมใช้งานในภูมิภาค
เริ่มต้นใช้งานและคำแนะนำ: https://aka.ms/openai/start

⚠️ ข้อจำกัดของโมเดลเก่า

คำเตือน: โมเดลเก่า (ก่อน gpt-4.1) อาจไม่รองรับฟีเจอร์ Responses API ทุกอย่างอย่างเต็มที่

จำกัดการใช้งานที่ทราบกับโมเดลเก่า:

พารามิเตอร์ reasoning: ไม่รองรับในหลายโมเดลที่ไม่มี reasoning หากจะย้ายให้ย้ายเฉพาะกรณีที่มี reasoning อยู่แล้วในโค้ดต้นทาง

พารามิเตอร์ seed: ไม่รองรับใน Responses API เลย — ลบออกจากคำขอทั้งหมด

ผลลัพธ์แบบมีโครงสร้างผ่าน text.format: โมเดลเก่าอาจไม่บังคับใช้สคีมา JSON แบบ strict: true ได้อย่างน่าเชื่อถือ

การประสานเครื่องมือ: GPT-5+ จัดการการเรียกเครื่องมือเป็นส่วนหนึ่งของ reasoning ภายใน โมเดลเก่าบน Responses ยังใช้งานได้แต่ไม่มีการรวมลึกนี้

ข้อจำกัดอุณหภูมิ: เมื่อย้ายไป gpt-5 อุณหภูมิต้องไม่กำหนดหรือกำหนดเป็น 1 โมเดลเก่าไม่มีข้อจำกัดนี้

โมเดล reasoning ซีรีส์ O (o1, o3-mini, o3, o4-mini)

โมเดลซีรีส์ O มีข้อจำกัดพารามิเตอร์เฉพาะตัว เมื่อย้ายแอปที่มุ่งเป้าไปยังโมเดลซีรีส์ O:

temperature: ต้องเป็น 1 (หรือละเว้น) โมเดลซีรีส์ O ไม่รับค่าที่ต่างจากนี้
max_completion_tokens → max_output_tokens: แอปที่ใช้ max_completion_tokens เฉพาะ Azure ต้องเปลี่ยนเป็น max_output_tokens ตั้งค่าสูง (4096+) เพราะโทเค็น reasoning นับในขีดจำกัดนี้
reasoning_effort: หากแอปใช้ reasoning_effort (ต่ำ/กลาง/สูง) ให้เก็บไว้ — Responses API รองรับพารามิเตอร์นี้สำหรับโมเดลซีรีส์ O
พฤติกรรมการสตรีม: โมเดลซีรีส์ O อาจเก็บบัฟเฟอร์ผลลัพธ์จน reasoning เสร็จก่อนส่งเหตุการณ์ delta ข้อความ การสตรีมยังทำงาน แต่ delta แรกอาจช้ากว่าโมเดล GPT
top_p: ไม่รองรับในซีรีส์ O — ให้ลบออกหากมี
การใช้เครื่องมือ: โมเดลซีรีส์ O รองรับเครื่องมือผ่าน Responses API เช่นเดียวกับโมเดล GPT แต่คุณภาพการประสานการเรียกเครื่องมือขึ้นกับแต่ละโมเดล

คำแนะนำเชิงรุก — ระหว่างสแกน: ตรวจสอบว่าแอปใช้โมเดลใด (ชื่อ deployment, ตัวแปรสภาพแวดล้อม, การตั้งค่า) หากเป็นโมเดลก่อน gpt-4.1 (ไม่ใช่ gpt-4.1+) แจ้งผู้ใช้ล่วงหน้า:

การย้ายจะทำงานกับข้อความพื้นฐาน แชท การสตรีม และเครื่องมือบนโมเดลปัจจุบันได้
โมเดลใหม่กว่า (gpt-5.1, gpt-5.2) ให้การประสานเครื่องมือที่ดีกว่า การบังคับใช้ผลลัพธ์แบบมีโครงสร้าง reasoning และความพร้อมใช้งานข้ามภูมิภาค
ควรพิจารณาอัปเกรด deployment เมื่อพร้อม — ไม่มีผลขัดขวางการย้ายตอนนี้

หลีกเลี่ยงการบล็อกหรือปฏิเสธให้ย้ายตามเวอร์ชันโมเดล คำแนะนำนี้เป็นข้อมูลเท่านั้น

GitHub Models ไม่รองรับ Responses API

GitHub Models (models.github.ai, models.inference.ai.azure.com) ไม่รองรับ Responses API

หากฐานโค้ดมีเส้นทางโค้ด GitHub Models (ดูที่ base_url ชี้ไปยัง models.github.ai หรือ models.inference.ai.azure.com) ให้ลบออกทั้งหมด ในการย้าย Responses API ต้องใช้ Azure OpenAI, OpenAI หรือปลายทางในเครื่องที่เข้ากันได้ (เช่น Ollama ที่รองรับ Responses)

การดำเนินการระหว่างสแกน:

ให้ติดธงเส้นทางโค้ด GitHub Models เพื่อการลบ

การย้ายเฟรมเวิร์ก

แอปหลายแอปใช้เฟรมเวิร์กระดับสูงบน OpenAI เมื่อย้ายเฟรมเวิร์กเหล่านี้ จะมีการเปลี่ยนแปลง API เฟรมเวิร์กเอง — ไม่ใช่แค่การเรียก OpenAI ขั้นต่ำ

Microsoft Agent Framework (MAF)

ตรวจสอบเวอร์ชัน MAF ของคุณก่อน — การย้ายขึ้นกับว่าคุณใช้ MAF 1.0.0+ หรือเบต้า/rc ก่อน 1.0.0

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

OpenAIChatClient ใช้ Responses API แล้ว — ไม่ต้องย้าย หากฐานโค้ดยังใช้ OpenAIChatCompletionClient แบบเก่า (ที่ใช้ chat.completions.create) ให้เปลี่ยนเป็น OpenAIChatClient

ก่อน	หลัง
`from agent_framework.openai import OpenAIChatCompletionClient`	`from agent_framework.openai import OpenAIChatClient`
`OpenAIChatCompletionClient(...)`	`OpenAIChatClient(...)`

ตรวจสอบเวอร์ชันของคุณด้วย: python -c "import agent_framework_openai; print(agent_framework_openai.__version__)"

MAF ก่อน 1.0.0 (รุ่นเบต้า/rc)

ใน MAF ก่อน 1.0.0 OpenAIChatClient ใช้ Chat Completions อัพเกรดเป็น agent-framework-openai>=1.0.0 ซึ่ง OpenAIChatClient ใช้ Responses API โดยดีฟอลต์

ไม่มีการเปลี่ยนแปลงอื่น — API ของ Agent และเครื่องมือเหมือนเดิม

LangChain (`langchain-openai`)

เพิ่ม use_responses_api=True ให้กับ ChatOpenAI() และอัพเดตการเข้าถึงผลลัพธ์จาก .content เป็น .text

ก่อน	หลัง
`ChatOpenAI(model=..., base_url=..., api_key=...)`	`ChatOpenAI(model=..., base_url=..., api_key=..., use_responses_api=True)`
`result['messages'][-1].content`	`result['messages'][-1].text`

ดูตัวอย่างโค้ดทั้งก่อนและหลังใน cheat-sheet.md

คำแนะนำการย้ายส่วนหน้า

Responses API เป็นเรื่องฝั่งเซิร์ฟเวอร์ ย้าย backend Python ของคุณ ส่วนหน้า (frontend) ควรยังคงตามสัญญา HTTP เดิมเว้นแต่ว่า backend เป็นเพียงชั้นผ่านบาง ๆ — กรณีนั้นให้พิจารณาใช้รูปแบบคำขอ Responses เพื่อกำจัดชั้นแปลง หาก frontend เรียก OpenAI โดยตรงด้วยคีย์ฝั่งไคลเอนต์ ให้ย้ายการเรียกเหล่านั้นไป backend ก่อน

การเลิกใช้งาน `@microsoft/ai-chat-protocol`

แพ็กเกจ npm @microsoft/ai-chat-protocol ถูกเลิกใช้และควรเปลี่ยนเป็น ndjson-readablestream หากพบในส่วนหน้า:

แก้แท็กสคริปต์ 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>

ลบการสร้างอินสแตนซ์ AIChatProtocolClient (new ChatProtocol.AIChatProtocolClient("/chat"))
เปลี่ยน client.getStreamedCompletion(messages) เป็นเรียก fetch() ตรงไปยังจุดสตรีมของ backend
เปลี่ยน for await (const response of result) เป็น for await (const chunk of readNDJSONStream(response.body))
ปรับเปลี่ยนการเข้าถึงคุณสมบัติจาก response.delta.content / response.error เป็น chunk.delta.content / chunk.error

เป้าหมาย

ระบุทุกจุดเรียก Python ที่ใช้ Chat Completions หรือ Completions แบบเก่าที่เรียกกับ Azure OpenAI
เสนอแผนการย้ายและลำดับขั้นสำหรับฐานโค้ด Python
ใช้การแก้ไขอย่างปลอดภัยและน้อยที่สุดเพื่อสลับไป Responses API
อัปเดตผู้เรียกเพื่อใช้สคีมาผลลัพธ์ของ Responses; ไม่มีหุ้มหลังความเข้ากันได้
รันการทดสอบ/ตรวจสอบ; แก้ไขปัญหาเล็กน้อยที่เกิดจากการย้าย
เตรียมชุดการเปลี่ยนแปลงที่เล็กและตรวจสอบได้ พร้อมสรุปสุดท้ายพร้อมการเปรียบเทียบ (ไม่ต้อง commit)

กฎข้อบังคับ

แก้ไขเฉพาะไฟล์ในพื้นที่ git เท่านั้น ห้ามเขียนนอกพื้นที่นี้
ไม่ต้องเก็บไว้ในช่องทางหลังความเข้ากันได้; ย้ายโค้ดไปยังรูปแบบ API ใหม่
หลีกเลี่ยงการทิ้งคอมเมนต์รอยตาย/เปลี่ยนผ่านหรือไฟล์สำรอง
รักษาลักษณะการสตรีมหากเคยใช้; มิฉะนั้นใช้แบบไม่สตรีม
ขออนุมัติก่อนรันคำสั่งหรือเรียกเครือข่ายถ้าอยู่ในโหมดอนุมัติ
หลีกเลี่ยงการรัน git add/git commit/git push; ผลลัพธ์ต้องเป็นใน working-tree เท่านั้น

ขั้นตอนที่ 0: ย้ายไคลเอนต์ Azure OpenAI (เงื่อนไขเบื้องต้น)

หากฐานโค้ดใช้ตัวสร้าง AzureOpenAI หรือ AsyncAzureOpenAI ให้ย้ายไปใช้ตัวสร้าง OpenAI / AsyncOpenAI แบบมาตรฐานก่อน ตัวสร้างเฉพาะ Azure ถูกเลิกใช้ใน openai>=1.108.1

ทำไมต้องใช้ปลายทาง v1 API?

ปลายทางใหม่ /openai/v1 ใช้ไคลเอนต์ OpenAI() แบบมาตรฐานแทน AzureOpenAI() ไม่ต้องใช้พารามิเตอร์ api_version และทำงานเหมือนกันทั้ง OpenAI และ Azure OpenAI โค้ดไคลเอนต์เดียวกันนี้รองรับอนาคต — ไม่ต้องจัดการเวอร์ชัน

การเปลี่ยนแปลงสำคัญ

ก่อน	หลัง
`AzureOpenAI`	`OpenAI`
`AsyncAzureOpenAI`	`AsyncOpenAI`
`azure_endpoint`	`base_url`
`azure_ad_token_provider`	`api_key`
`api_version=...`	ลบทิ้งทั้งหมด

รายการล้างข้อมูล

ลบอาร์กิวเมนต์ api_version จากการสร้างไคลเอนต์
ลบตัวแปรสภาพแวดล้อม AZURE_OPENAI_VERSION / AZURE_OPENAI_API_VERSION จาก .env, การตั้งค่าแอป และไฟล์ Bicep/โครงสร้างพื้นฐาน
เปลี่ยนชื่อ AZURE_OPENAI_CLIENT_ID → AZURE_CLIENT_ID ใน .env, การตั้งค่าแอป, Bicep/โครงสร้างพื้นฐาน และไฟล์ตัวอย่างทดสอบ (ตามแนวทางมาตรฐาน Azure Identity SDK)
แน่ใจว่า openai>=1.108.1 ใน requirements.txt หรือ pyproject.toml

ย้ายตัวแปรสภาพแวดล้อม

ตัวแปรสภาพแวดล้อมเดิม	การดำเนินการ	หมายเหตุ
`AZURE_OPENAI_VERSION`	ลบ	ไม่ต้องใช้ `api_version` กับปลายทาง v1
`AZURE_OPENAI_API_VERSION`	ลบ	เหมือนกันกับด้านบน
`AZURE_OPENAI_CLIENT_ID`	เปลี่ยนชื่อ → `AZURE_CLIENT_ID`	ตามมาตรฐาน Azure Identity SDK สำหรับ `ManagedIdentityCredential(client_id=...)`
`AZURE_OPENAI_ENDPOINT`	เก็บไว้	ยังคงต้องใช้สำหรับสร้าง `base_url`
`AZURE_OPENAI_CHAT_DEPLOYMENT`	เก็บไว้	ใช้เป็นพารามิเตอร์ `model` ใน `responses.create`
`AZURE_OPENAI_API_KEY`	เก็บไว้	ใช้เป็น `api_key` สำหรับการยืนยันตัวตนด้วยคีย์

ตัวอย่างการตั้งค่าไคลเอนต์ (ซิงค์, อะซิงค์, EntraID, คีย์ API, หลาย tenant) ดูใน cheat-sheet.md

ขั้นตอนที่ 1: ตรวจจับจุดเรียกใช้งานแบบเก่า

รันสคริปต์ detect_legacy.py เพื่อค้นหาจุดเรียกใช้งานทั้งหมดที่ต้องย้าย:

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

หรือรันการค้นหาเหล่านี้ด้วยตนเอง — ทุกคำที่ตรงเป็นเป้าหมายการย้าย:

# การเรียก API รุ่นเก่า (ต้องเขียนใหม่)
rg "chat\.completions\.create"
rg "ChatCompletion\.create"
rg "Completion\.create"

# ตัวสร้างไคลเอ็นต์ Azure ที่เลิกใช้แล้ว (ต้องเปลี่ยนใหม่)
rg "AzureOpenAI\("
rg "AsyncAzureOpenAI\("

# รูปแบบการเข้าถึงโครงสร้างการตอบกลับ (ต้องอัปเดต)
rg "choices\[0\]\.message\.content"
rg "choices\[0\]\.delta\.content"
rg "choices\[0\]\.message\.function_call"
rg "choices\[0\]\.message\.tool_calls"

# นิยามเครื่องมือในรูปแบบซ้อนเก่า (ต้องปรับเป็นโครงสร้างแบน)
rg '"function":\s*{\s*"name"'
rg "pydantic_function_tool"

# ผลลัพธ์เครื่องมือในรูปแบบเก่า (ต้องแปลงเป็น function_call_output)
rg '"role":\s*"tool"'
rg '"tool_call_id"'

# พารามิเตอร์ที่เลิกใช้แล้ว (ต้องลบหรือเปลี่ยนชื่อ)
rg "response_format"
rg "max_tokens\b"        # เปลี่ยนชื่อเป็น max_output_tokens
rg "['\"]seed['\"]"      # remove entirely

# ตัวแปรสภาพแวดล้อมที่เลิกใช้แล้ว (ต้องทำความสะอาด)
rg "AZURE_OPENAI_API_VERSION|AZURE_OPENAI_VERSION"
rg "AZURE_OPENAI_CLIENT_ID"  # ควรเป็น AZURE_CLIENT_ID

# จุดเชื่อมต่อโมเดล GitHub (ต้องลบ — API ตอบกลับไม่ได้รับการสนับสนุน)
rg "models\.github\.ai|models\.inference\.ai\.azure"

# รูปแบบเก่าของเฟรมเวิร์กระดับสูง (ต้องอัปเดต)
rg "OpenAIChatCompletionClient"  # MAF 1.0.0+: เปลี่ยนเป็น OpenAIChatClient
rg "ChatOpenAI\(" | grep -v "use_responses_api"  # LangChain: ต้องใช้ use_responses_api=True

# โครงสร้างพื้นฐานการทดสอบ (ต้องอัปเดต)
rg "ChatCompletionChunk|AsyncCompletions\.create" tests/
rg "_azure_ad_token_provider" tests/
rg "prompt_filter_results|content_filter_results" tests/
rg "choices\[0\]" tests/

# การเข้าถึงข้อมูลข้อผิดพลาดตัวกรองเนื้อหา (ต้องอัปเดต — โครงสร้างเปลี่ยนแปลง)
rg 'innererror.*content_filter_result|error\.body\["innererror"\]'
rg "content_filter_result\[" # รูปแบบเอกพจน์เก่า — ตอนนี้เป็น content_filter_results (พหูพจน์) ภายในอาร์เรย์ content_filters

# การเรียก HTTP ดิบไปยังจุดสิ้นสุด Chat Completions (ต้องอัปเดต URL)
rg "/openai/deployments/.*/chat/completions"
rg "api-version="

การประมาณ (ตรวจจับและเขียนใหม่)

ไคลเอนต์ Chat Completions: client.chat.completions.create → client.responses.create(...).
ตัวสร้างลูกค้า Azure: AzureOpenAI(...) → OpenAI(base_url=..., api_key=...).
เครื่องมือ: แปลงคำจำกัดความเครื่องมือเรียกฟังก์ชันจากรูปแบบซ้อนกัน ({"type": "function", "function": {"name": ...}}) เป็นรูปแบบแบนของ Responses ({"type": "function", "name": ...}); ใช้ tool_choice; ส่งคืนผลลัพธ์ของเครื่องมือเป็นรายการ {"type": "function_call_output", "call_id": ..., "output": ...} (ไม่ใช่ {"role": "tool", ...}).
รอบเครื่องมือ: เมื่อโมเดลส่งคืนการเรียกฟังก์ชัน ให้แนบรายการ response.output ลงในการสนทนา (ไม่ใช่ dict แบบแมนนวล {"role": "assistant", "tool_calls": [...]}) จากนั้นแนบรายการ function_call_output สำหรับแต่ละผลลัพธ์.
ตัวอย่างเครื่องมือแบบ few-shot: หากการสนทนารวมตัวอย่างการเรียกเครื่องมือแบบกำหนดไว้ล่วงหน้า ให้แปลงเป็นรายการ {"type": "function_call", "id": "fc_...", "call_id": "fc_...", ...} + {"type": "function_call_output", ...} ต้องให้ ID เริ่มต้นด้วย fc_.
pydantic_function_tool(): ตัวช่วยนี้ยังคงสร้างรูปแบบซ้อนแบบเก่าและ ไม่เข้ากันได้ กับ responses.create() ให้แทนที่ด้วยคำจำกัดความเครื่องมือแบบแมนนวลหรือใช้ตัวห่อแปลงรูปแบบแบน.
หลายรอบ: รักษาประวัติการสนทนาในแอป; ส่งผ่านรอบก่อนหน้าผ่านรายการ input.
การจัดรูปแบบ: แทนที่ response_format บนระดับบนสุดของ Chat ด้วย text.format ใน Responses รูปแบบมาตรฐาน: text={"format": {"type": "json_schema", "name": "Output", "strict": True, "schema": {...}}}.
รายการเนื้อหา: แทนที่ Chat content[].type: "text" ด้วย Responses content[].type: "input_text" สำหรับรอบของผู้ใช้/ระบบ.
รายการเนื้อหารูปภาพ: แทนที่ Chat content[].type: "image_url" ด้วย Responses content[].type: "input_image" ฟิลด์ image_url เปลี่ยนจากออบเจ็กต์ซ้อน {"url": "..."} เป็นสตริงแบน ดูตารางสรุปสำหรับตัวอย่างก่อน/หลัง.
ความพยายามในการให้เหตุผล: ย้ายเฉพาะ reasoning หากมีอยู่แล้วในโค้ดเดิม.
การจัดการข้อผิดพลาดตัวกรองเนื้อหา: โครงสร้าง body ของข้อผิดพลาดเปลี่ยนจากเดิม Chat Completions ใช้ error.body["innererror"]["content_filter_result"] (เอกพจน์); Responses API ใช้ error.body["content_filters"][0]["content_filter_results"] (พหูพจน์ อยู่ในอาเรย์) โค้ดที่เข้าถึง innererror จะเกิด KeyError ให้เขียนใหม่ใช้เส้นทางใหม่.
การเรียก HTTP แบบดิบ: หากแอปเรียก REST API ของ Azure OpenAI โดยตรง (ผ่าน requests, httpx ฯลฯ) ใช้ /openai/deployments/{name}/chat/completions?api-version=... ให้เขียนใหม่เป็น /openai/v1/responses ร่างคำขอเปลี่ยน: messages → input เพิ่ม max_output_tokens และ store: false ลบพารามิเตอร์ query api-version ร่างการตอบกลับเปลี่ยน: choices[0].message.content → output[0].content[0].text (หมายเหตุ: output_text เป็นคุณสมบัติสะดวกของ SDK ซึ่งไม่มีใน REST JSON ต้นฉบับ).

ขั้นตอนที่ 2: ใช้การย้ายข้อมูล

หมายเหตุการย้ายข้อมูล (Chat Completions → Responses)

ทำไมต้องย้าย: Responses คือ API รวมสำหรับข้อความ, เครื่องมือ, และการสตรีม; Chat Completions เป็นของเดิม กับ GPT-5 จำเป็นต้องใช้ Responses เพื่อประสิทธิภาพดีที่สุด.
HTTP: จุดสิ้นสุด Azure เปลี่ยนจาก /openai/deployments/{name}/chat/completions เป็น /openai/v1/responses.
ฟิลด์: messages → input, max_tokens → max_output_tokens อุณหภูมิยังคงเหมือนเดิม.
การจัดรูปแบบ: response_format → text.format โดยใช้วัตถุที่ถูกต้อง.
รายการเนื้อหา: แทนที่ Chat content[].type: "text" ด้วย Responses content[].type: "input_text" สำหรับรอบระบบ/ผู้ใช้.
รายการเนื้อหารูปภาพ: แทนที่ Chat content[].type: "image_url" ด้วย Responses content[].type: "input_image" แบนฟิลด์ image_url จาก {"image_url": {"url": "..."}} เป็น {"image_url": "..."} (เป็นสตริงธรรมดา — อาจเป็น URL HTTPS หรือ data URI ประเภท data:image/...;base64,...).

แผนที่พารามิเตอร์อ้างอิง

Chat Completions	Responses API
`prompt`	`input`
`messages`	`input` (อาเรย์ของรายการ)
`max_tokens`	`max_output_tokens`
`response_format`	`text.format` (วัตถุ)
`temperature`	`temperature` (ไม่เปลี่ยนแปลง)
`stop`	`stop` (ไม่เปลี่ยนแปลง)
`frequency_penalty`	`frequency_penalty` (ไม่เปลี่ยนแปลง)
`presence_penalty`	`presence_penalty` (ไม่เปลี่ยนแปลง)
`tools` / function-calling	`tools` (ไม่เปลี่ยนแปลง)
`seed`	ลบ (ไม่รองรับ)
`store`	`store` (ตั้งเป็น `false`)
`content[].type: "text"`	`content[].type: "input_text"`
`content[].type: "image_url"`	`content[].type: "input_image"`
`"image_url": {"url": "..."}`	`"image_url": "..."` (สตริงแบน)

สำหรับตัวอย่างโค้ดก่อน/หลังแบบสมบูรณ์ ดูที่ cheat-sheet.md.

สำหรับการย้ายโครงสร้างทดสอบ (mocks, snapshots, assertions) ดูที่ test-migration.md.

สำหรับการแก้ไขปัญหาข้อผิดพลาดและปัญหาต่าง ๆ ดูที่ troubleshooting.md.

การเก็บรักษาข้อมูล & สถานะ

ตั้งค่า store: false ในคำขอ Responses ทั้งหมด.
อย่าพึ่งพา ID ข้อความก่อนหน้าหรือบริบทที่เก็บไว้ในเซิร์ฟเวอร์; เก็บสถานะแบบจัดการโดยไคลเอนต์และลดเมตาดาต้าให้น้อยที่สุด.

เกณฑ์การยอมรับ

ด่านระดับโค้ด (ต้องผ่านทั้งหมด)

[ ] ไม่มีการจับคู่สำหรับ rg "chat\.completions\.create|ChatCompletion\.create|Completion\.create" ในไฟล์ที่ย้ายแล้ว.
[ ] ไม่มีการจับคู่สำหรับ rg "AzureOpenAI\(|AsyncAzureOpenAI\(" — ตัวสร้างทั้งหมดใช้ OpenAI/AsyncOpenAI กับจุดสิ้นสุด v1.
[ ] ไม่มีการจับคู่สำหรับ rg "models\.github\.ai|models\.inference\.ai\.azure" — ลบเส้นทางโค้ด GitHub Models.
[ ] ไม่มีการจับคู่สำหรับ rg "OpenAIChatCompletionClient" — โค้ด MAF 1.0.0+ ใช้ OpenAIChatClient (ซึ่งใช้ Responses API) ในเวอร์ชันก่อน 1.0.0 ให้ปรับเป็น agent-framework-openai>=1.0.0.
[ ] ทุกการเรียก ChatOpenAI(...) รวม use_responses_api=True.
[ ] ไม่มีการจับคู่สำหรับ rg "choices\[0\]" — ทุกการเข้าถึงผลลัพธ์ใช้ resp.output_text หรือสคีม่าเอาต์พุต Responses.
[ ] ไม่มี response_format บนระดับบนสุด; ทุกผลลัพธ์มีโครงสร้างใช้ text={"format": {...}}.
[ ] ใน requirements.txt หรือ pyproject.toml มี openai>=1.108.1 และ azure-identity; ติดตั้ง dependencies ใหม่แล้ว.
[ ] ตั้งค่า store=False ในทุกการเรียก responses.create.
[ ] ไม่มี api_version ในการสร้างไคลเอนต์; ลบ AZURE_OPENAI_API_VERSION ออกจากไฟล์ env และโครงสร้างพื้นฐาน.

ด่านโครงสร้างทดสอบ (ต้องผ่านทั้งหมด)

[ ] ไม่มีการจับคู่สำหรับ rg "ChatCompletionChunk|AsyncCompletions\.create|chat\.completions" tests/.
[ ] ไม่มีการจับคู่สำหรับ rg "_azure_ad_token_provider" tests/ — ปรับปรุง assertions ให้ตรวจสอบ isinstance(client, AsyncOpenAI) หรือ base_url.
[ ] ไม่มีการจับคู่สำหรับ rg "prompt_filter_results|content_filter_results" tests/ — ลบ mocks ตัวกรองเฉพาะ Azure.
[ ] ใช้ fixture mocks kwargs.get("input") แทน kwargs.get("messages").
[ ] ปรับปรุงไฟล์ snapshot / golden เป็นรูปแบบสตรีมของ Responses (ไม่มี choices[0], function_call, logprobs ฯลฯ).
[ ] pytest ผ่านโดยไม่มีข้อผิดพลาดหลังจากแก้ไขการทดสอบทั้งหมด.

ด่านพฤติกรรม (ตรวจสอบด้วยตนเองหรือผ่านชุดทดสอบ)

[ ] การคอมพลีตพื้นฐาน: responses.create แบบไม่สตรีมส่งคืน output_text ที่ไม่ว่าง.
[ ] ความเท่าเทียมแบบสตรีม: หากโค้ดเดิมใช้การสตรีม โค้ดที่ย้ายจะสตรีมและให้เหตุการณ์ response.output_text.delta ที่มีเดลต้าไม่ว่าง.
[ ] เอาต์พุตโครงสร้าง: หากใช้ text.format กับ json_schema json.loads(resp.output_text) ผ่านและตรงกับสคีม่า.
[ ] ลูปเรียกเครื่องมือ: หากใช้เครื่องมือ โมเดลจะส่งคำสั่งเรียกเครื่องมือ, แอปจะประมวลผล, และคำขอต่อไปจะส่งคืน output_text สุดท้าย (ไม่มีลูปไม่สิ้นสุด).
[ ] ความเท่าเทียมแบบ Async: หากใช้ AsyncAzureOpenAI, การใช้ AsyncOpenAI แบบเทียบเท่าทำงานด้วย await.
[ ] อัตราข้อผิดพลาด: ไม่มีข้อผิดพลาด 400/401/404 ใหม่เมื่อเทียบกับเส้นฐานก่อนย้าย.

ผลงานที่ส่งมอบ

สรุปรายการไฟล์ที่แก้ไข, จำนวนจุดเรียกใช้เดิมและใหม่, และขั้นตอนถัดไป.
การเปลี่ยนแปลงเป็นการแก้ไขใน working-tree เท่านั้น (ไม่มี commit).

เวอร์ชันที่ต้องใช้ของ SDK

แพ็กเกจ	เวอร์ชันขั้นต่ำ
`openai`	`>=1.108.1`
`azure-identity`	ล่าสุด (สำหรับการรับรองความถูกต้อง EntraID)

แหล่งอ้างอิง

ปฏิเสธความรับผิดชอบ: เอกสารนี้ได้รับการแปลโดยใช้บริการแปลภาษา AI Co-op Translator ขณะที่เราพยายามให้ความถูกต้อง โปรดทราบว่าการแปลโดยอัตโนมัติอาจมีข้อผิดพลาดหรือความไม่ถูกต้อง เอกสารต้นฉบับในภาษาต้นทางควรถูกพิจารณาเป็นแหล่งข้อมูลที่เชื่อถือได้ สำหรับข้อมูลที่สำคัญ แนะนำให้ใช้การแปลโดยมนุษย์มืออาชีพ เราไม่รับผิดชอบต่อความเข้าใจผิดหรือการตีความที่ผิดพลาดที่เกิดขึ้นจากการใช้การแปลนี้