Премини към основното съдържание
Български— Изберете език
Меню

Постепенна миграция към Responses API

Урок 12 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Защо и кога да мигрирате
  2. Стъпка 1: Идентифицирайте функциите, които използвате
  3. Стъпка 2: Мигрирайте основните извиквания
  4. Стъпка 3: Мигрирайте многократни разговори
  5. Стъпка 4: Използвайте предимствата на новите функции
  6. Препоръчителна стратегия за миграция
  7. Ключови изводи
  8. Проверете знанията си

Обновено на 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_text
  • max_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

Препоръчителна стратегия за миграция

Вместо да мигрирате всичко наведнъж, действайте на етапи:

  1. Идентифицирайте извикванията на Chat Completions във Вашия код
  2. Класифицирайте ги по сложност (основни → стрийминг → извикване на функции)
  3. Мигрирайте първо новите крайни точки или функции (greenfield)
  4. След това мигрирайте най-простите съществуващи извиквания
  5. Задръжте 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, съществуващите крайни точки се конвертират една по една с повторно тестване на промптовете — сравняването на двата формата насочва конвертирането.

Разберете остарялото, изградете за модерното: планът за постепенна миграция на курса е Вашата пътна карта — без „голям взрив“.