Responses API срещу Chat Completions: Защо да мигрирате
На тази страница
Responses API срещу Chat Completions
API за Chat Completions служи като стандарт в продължение на години и голяма част от кода, който откривате онлайн, все още го използва. Въпреки това, от 2025 г. насам OpenAI го определи като остарял (legacy) и препоръчва Responses API за всички нови проекти. Този урок сравнява двата интерфейса, като се фокусира върху разликите, които действително оказват влияние върху Вашия код.
Фундаментални промени
При Chat Completions Вие изграждахте списък със съобщения и изпращахте целия списък при всяко извикване. Състоянието на разговора се съхраняваше във Вашето приложение, а никога на сървъра:
from openai import OpenAI
client = OpenAI()
# Стар модел — Chat Completions (остарял)
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"},
]
)
print(response.choices[0].message.content)
# Result: "The capital of France is Paris."
Responses API свежда това същото извикване до два параметъра и осигурява директен достъп до генерирания текст. Системното съобщение става параметърът instructions, а извличането на съдържанието вече не изисква навигиране през choices[0].message.content:
from openai import OpenAI
client = OpenAI()
# Нов модел — Responses API
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the capital of France?"
)
print(response.output_text)
# Result: "The capital of France is Paris."
Управление на сесиите от страна на сървъра
Това предлага най-непосредствената полза. API поддържа състоянието на разговора, така че трябва само да препратите предишния отговор чрез неговия ID. Представете си асистент за поддръжка: при десетия завой подходът с Chat Completions Ви принуждаваше да изпратите отново предишните девет размени, което означаваше, че плащате отново за тези токени. Тук е достатъчно едно единствено поле:
# Първи въпрос
response = client.responses.create(
model="gpt-5.6-terra",
input="My name is Marie."
)
# Втори въпрос — контекстът се запазва автоматично
followup = client.responses.create(
model="gpt-5.6-terra",
input="What is my name?",
previous_response_id=response.id
)
print(followup.output_text)
# Result: "Your name is Marie."
Гарантиран JSON, а не „надявам се за JSON“
Второто голямо подобрение засяга структурираните изходни данни. Вие описвате очаквания формат и Responses API гарантира, че отговорът ще се придържа към Вашата JSON схема – това Ви позволява да десериализирате данните без предпазни мрежи. Формуляр за регистрация, който извлича информация от свободен текст, вече няма да се срине само защото моделът реши да добави уводно изречение преди своя JSON:
from pydantic import BaseModel
class City(BaseModel):
name: str
country: str
population: int
response = client.responses.create(
model="gpt-5.6-terra",
input="Give me information about Paris.",
text={"format": {"type": "json_schema", "json_schema": {
"name": "city",
"strict": True,
"schema": City.model_json_schema()
}}}
)
print(response.output_text)
# Result: {"name": "Paris", "country": "France", "population": 2161000}
Извикване на функции и стрийминг
Декларирането на инструменти следва същата логика на опростяване: дескрипторът на функцията се декларира плоско в tools, а извикването, поискано от модела, се появява директно в response.output, без допълнителни нива на влагане.
response = client.responses.create(
model="gpt-5.6-terra",
input="What is the weather like in Lyon?",
tools=[{
"type": "function",
"name": "get_meteo",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Name of the city"}
},
"required": ["city"]
}
}]
)
# API връща функцията за изпълнение директно
for item in response.output:
if item.type == "function_call":
print(f"Function: {item.name}, Arguments: {item.arguments}")
# Result: Function: get_meteo, Arguments: {"city": "Lyon"}
Стриймингът вече не връща поток от недиференцирани парчета, а типизирани събития. Вие филтрирате по event.type и знаете точно какво обработвате – текстов фрагмент, аргумент на функция или край на генерирането:
stream = client.responses.create(
model="gpt-5.6-terra",
input="Tell a short story.",
stream=True
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
Бързо ръководство за миграция
| Chat Completions | Responses API |
|---|---|
client.chat.completions.create() | client.responses.create() |
messages=[...] | input="..." или input=[...] |
response.choices[0].message.content | response.output_text |
| Ръчна история | previous_response_id |
response_format | text={"format": {...}} |
tools + tool_choice | tools (опростено) |
Трябва ли да мигрирате веднага?
API за Chat Completions остава функционален и не се премахва. Съществуващ код, който работи, не изисква промени и разчита на тестови конвейер, изграден около стария формат, няма никаква полза от спешно пренаписване. По същия начин, ако зависите от библиотека на трета страна, която все още не поддържа Responses API, изчакайте нейното обновяване. Въпреки това, за всеки нов проект, отговорът е ясен: Responses API е отправната точка и остатъкът от този курс продължава от това предположение.
Ключови изводи
- Responses API замества Chat Completions с по-прост интерфейс
- Управлението на сесиите от страна на сървъра елиминира необходимостта от повторно изпращане на историята
- Структурираният изход и извикването на функции са интегрирани нативно
- Миграцията е проста: концепциите остават същите, променя се само синтаксисът