Постепенна миграция към Responses API
На тази страница
Обновено на 3 ноември 2026 г.: Предишното съпоставяне на параметрите показваше, че
max_tokensзапазва името си в Responses API; таблицата на xAI го променя наmax_output_tokens, а имената на броячите за използване също се променят. Източник: Сравнение с Chat Completions.
Защо и кога да мигрирате
Крайната точка Chat Completions е означена като остаряла (legacy). Тя ще продължи да работи, но няма да бъдат добавяни нови функции към нея. Ако Вашето приложение се нуждае от сървърни инструменти (уеб търсене, изпълнение на код), съхранение на разговори или криптирано разсъждение, миграцията към Responses API става необходима.
Добрата новина: тази миграция може да се извърши постепенно. Не е необходимо да пренаписвате всичко наведнъж.
Стъпка 1: Идентифицирайте функциите, които използвате
Преди да мигрирате, направете преглед на това какво използва Вашето приложение с Chat Completions:
# Audit your existing code
# Look for these patterns:
# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)
# 2. Streaming
client.chat.completions.create(..., stream=True)
# 3. Function calling
client.chat.completions.create(..., tools=[...])
# 4. Vision (images)
# messages with content as array [text, image_url]
# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed
Основните извиквания и стриймингът са най-лесни за миграция. Извикването на функции изисква адаптиране на формата. Визията работи по подобен начин.
Стъпка 2: Мигрирайте основните извиквания
Миграцията на просто извикване следва този шаблон:
# BEFORE — Chat Completions
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
)
texte = response.choices[0].message.content
# AFTER — Responses API
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input="Hello!"
)
texte = response.output_text
Съпоставяне на полетата
Основните промени са:
messagesс роляsystem→instructions(специализиран параметър)messagesс роляuser→input(обикновен низ)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, според таблицата за съпоставяне на xAI;temperatureзапазва името сиresponse.usage.prompt_tokensиcompletion_tokens→input_tokensиoutput_tokens(детайли:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Стъпка 3: Мигрирайте многократни разговори
Тук Responses API опростява нещата. Вместо да реконструирате историята при всяка заявка, Вие ги свързвате чрез ID:
# BEFORE — Chat Completions (manage history yourself)
historique = [
{"role": "system", "content": "You are a helpful assistant."}
]
def envoyer_message(texte: str) -> str:
historique.append({"role": "user", "content": texte})
response = client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=historique
)
reponse = response.choices[0].message.content
historique.append({"role": "assistant", "content": reponse})
return reponse
# AFTER — Responses API (server manages history)
dernier_id = None
def envoyer_message(texte: str) -> str:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
instructions="You are a helpful assistant.",
input=texte,
previous_response_id=dernier_id
)
dernier_id = response.id
return response.output_text
Кодът е по-прост и вече не трябва да управлявате масива с сообщения ръчно.
Стъпка 4: Използвайте предимствата на новите функции
След миграцията можете да се възползвате от функции, достъпни само в Responses API:
Вградено уеб търсене
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest developments in generative AI?",
tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs
Съхранение на отговора
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analyze this document...",
store=True # Keeps for 30 days
)
# Retrieve later
stored = client.responses.retrieve(response.id)
Криптирано разсъждение
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this complex problem...",
include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests
Препоръчителна стратегия за миграция
Вместо да мигрирате всичко наведнъж, действайте на етапи:
- Идентифицирайте извикванията на Chat Completions във Вашия код
- Класифицирайте ги по сложност (основни → стрийминг → извикване на функции)
- Мигрирайте първо новите крайни точки или функции (greenfield)
- След това мигрирайте най-простите съществуващи извиквания
- Задръжте Chat Completions за интеграции с трети страни, които го изискват (LangChain и др.)
Временно съвместно съществуване
Напълно приемливо е да изпълнявате двете крайни точки успоредно по време на прехода:
# Wrapper that abstracts the endpoint used
class GrokClient:
def __init__(self, use_responses: bool = False):
self.use_responses = use_responses
self.client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
def generate(self, system: str, user_message: str) -> str:
if self.use_responses:
response = self.client.responses.create(
model="grok-4.20-0309-reasoning",
instructions=system,
input=user_message
)
return response.output_text
else:
response = self.client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[
{"role": "system", "content": system},
{"role": "user", "content": user_message}
]
)
return response.choices[0].message.content
Този подход Ви позволява да превключвате постепенно, като тествате всяка миграция индивидуално.
Ключови изводи
- Миграцията може да бъде постепенна: няма нужда да пренаписвате всичко наведнъж
- Основни промени:
messages→input/instructions,choices[0].message.content→output_text - Многократните разговори преминават от масив с сообщения към просто
previous_response_id - Responses API осигурява достъп до ексклузивни функции (web_search, съхранение, криптирано разсъждение)
- Изпълнявайте двете крайни точки успоредно по време на прехода и мигрирайте според реда на сложност
Проверете знанията си
Остарелият API е разбран — и миграцията е подготвена.
1. Какво означава статутът на остарял и безсъстоятелен (stateless) за Chat Completions?
Отговор: Крайната точка остава поддържана, но вече не се развива: като безсъстоятелна, тя изисква повторно изпращане на цялата история при всяко извикване — Responses API е модерният път.
2. Кои роли структурират съобщенията?
Отговор: system (и developer), user, assistant — рамката, заявките, отговорите: цялата история започва отначало при всяка заявка.
3. Как да използвате съществуващия код на OpenAI с Grok?
Отговор: Чрез промяна на base_url на https://api.x.ai/v1 и API ключа — съвместимостта на формата се грижи за останалото, включително OpenAI SDK и Vercel AI SDK.
4. Какво четете в отговора и използването?
Отговор: choices носи отговори с finish_reason; usage детайлизира токените, включително reasoning_tokens за моделите за разсъждение — основата за проследяване на разходите.
5. Как да мигрирате чисто към Responses API?
Отговор: Постепенно: нови разработки в Responses, съществуващите крайни точки се конвертират една по една с повторно тестване на промптовете — сравняването на двата формата насочва конвертирането.
Разберете остарялото, изградете за модерното: планът за постепенна миграция на курса е Вашата пътна карта — без „голям взрив“.