Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Migrazzjoni Gradwali lejn l-API tar-Risposti

Lezzjoni 12 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Għaliex u meta timmigra
  2. Pass 1: Identifika l-karatteristiċi li tuża
  3. Pass 2: Iċċaqlaq is-sejħiet bażiċi
  4. Pass 3: Iċċaqlaq il-konversazzjonijiet multi-turn
  5. Pass 4: Sfrutta karatteristiċi ġodda
  6. Strateġija ta’ migrazzjoni rrakkomandata
  7. Punti Ewlenin
  8. Ittestja l-għarfien tiegħek

Aġġornat fit-3 ta’ Novembru, 2026: Il-mappatura tal-parametri kienet tindika li max_tokens iżomm ismu fl-API tar-Risposti; it-tabella ta’ xAI tbiddlu għal max_output_tokens, u l-kontaturi tal-użu jbiddlu isimhom ukoll. Sors: Tqabbil mal-Chat Completions.

Għaliex u meta timmigra

L-endpoint tal-Chat Completions huwa mmarkat bħala antikwat (legacy). Ikompli jaħdem, iżda l-ebda karatteristika ġdida ma se tiżdied miegħu. Jekk l-applikazzjoni tiegħek teħtieġ għodod fuq is-server (tiftix fil-web, eżekuzzjoni tal-kodiċi), ħażna tal-konversazzjonijiet, jew raġunar ikkrittat, il-migrazzjoni lejn l-API tar-Risposti ssir meħtieġa.

L-aħbar tajba: din il-migrazzjoni tista’ sseħħ gradwalment. M’għandekx bżonn terġa’ tikteb kollox f’daqqa.

Pass 1: Identifika l-karatteristiċi li tuża

Qabel ma timmigra, agħmel inventarju ta’ x’tuża l-applikazzjoni tiegħek mal-Chat Completions:

# Awditja l-kodiċi eżistenti tiegħek
# Fittex dawn il-mudelli:

# 1. Sejħiet bażiċi (test sempliċi)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Sejħa ta' funzjonijiet
client.chat.completions.create(..., tools=[...])

# 4. Viżjoni (immaġnijiet)
# messages b'kontenut bħala array [text, image_url]

# 5. Parametri tal-ġenerazzjoni
# temperature, max_tokens, top_p, stop, seed

Is-sejħiet bażiċi u l-streaming huma l-aktar faċli biex jiġu mmodifikati. Is-sejħa tal-funzjonijiet teħtieġ adattament tal-format. Il-viżjoni taħdem bl-istess mod.

Pass 2: Iċċaqlaq is-sejħiet bażiċi

Il-migrazzjoni ta’ sejħa sempliċi ssegwi dan il-mudell:

# QABEL — 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

# WARA — Responses API
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Mappatura tal-oqsma

Il-bidliet ewlenin huma:

  • messages bir-rwol system → instructions (parametru ddedikat)
  • messages bir-rwol user → input (string sempliċi)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, skont it-tabella tal-mappatura ta’ xAI; temperature iżomm ismu
  • response.usage.prompt_tokens u completion_tokens → input_tokens u output_tokens (dettalji: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Pass 3: Iċċaqlaq il-konversazzjonijiet multi-turn

Hawnhekk l-API tar-Risposti tissimplifika l-affarijiet. Minflok ma terġa’ tibni l-istorja ma’ kull talba, tgħaqqadhom bl-ID:

# QABEL — Chat Completions (immaniġġja l-istorja int stess)
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

# WARA — Responses API (is-server jimmaniġġja l-istorja)
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

Il-kodiċi huwa aktar sempliċi u m’għadekx trid timmaniġġja l-array tal-messaġġi manwalment.

Pass 4: Sfrutta karatteristiċi ġodda

Ladarba timmigra, tista’ tuża karatteristiċi esklużivi għall-API tar-Risposti:

Tiftix fil-web integrat

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# Ir-risposta tinkludi ċitazzjonijiet b'URLs tas-sors

Ħażna tar-risposta

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Iżomm għal 30 jum
)

# Irkupra aktar tard
stored = client.responses.retrieve(response.id)

Raġunar ikkrittat

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# Ir-raġunar ikkrittat jista' jerġa' jintuża f'talbiet sussegwenti

Strateġija ta’ migrazzjoni rrakkomandata

Minflok ma timmigra kollox f’daqqa, ipproċedi b’passi:

  1. Identifika s-sejħiet tal-Chat Completions fil-kodiċi tiegħek
  2. Ikklassifikahom skont il-kumplessità (bażiku → streaming → sejħa ta’ funzjonijiet)
  3. Iċċaqlaq l-ewwel endpoints jew karatteristiċi ġodda (greenfield)
  4. Imbagħad iċċaqlaq l-aktar sejħiet eżistenti sempliċi
  5. Żomm il-Chat Completions għal integrazzjonijiet ta’ partijiet terzi li jeħtieġuhom (LangChain, eċċ.)

Koeżistenza temporanja

Huwa perfettament aċċettabbli li tħaddem iż-żewġ endpoints ħdejn xulxin matul it-tranżizzjoni:

# Wrapper li jastratta l-endpoint użat
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

Dan l-approċċ jippermettilek tibdel gradwalment billi tittestja kull migrazzjoni individwalment.

Punti Ewlenin

  • Il-migrazzjoni tista’ tkun gradwali: m’hemmx bżonn terġa’ tikteb kollox f’daqqa
  • Bidliet ewlenin: messages → input/instructions, choices[0].message.content → output_text
  • Il-konversazzjonijiet multi-turn jimxu minn array ta’ messaġġi għal previous_response_id sempliċi
  • L-API tar-Risposti tagħti aċċess għal karatteristiċi esklużivi (web_search, ħażna, raġunar ikkrittat)
  • Ħaddem iż-żewġ endpoints ħdejn xulxin matul it-tranżizzjoni u iċċaqlaq skont l-ordni tal-kumplessità

Ittestja l-għarfien tiegħek

L-API antika nftiehmet—u l-migrazzjoni tħejjiet.

1. X'inhu t-tifsira tal-istatus antikwat u mingħajr stat (stateless) tal-Chat Completions?

Tweġiba: L-endpoint jibqa’ appoġġjat iżda ma jevolvix aktar: mingħajr stat, jeħtieġ li terġa’ tibgħat l-istorja kollha ma’ kull sejħa—l-API tar-Risposti hija t-triq moderna.

2. Liema rwoli jistrutturaw il-messaġġi?

Tweġiba: system (u developer), user, assistant—il-qafas, it-talbiet, ir-risposti: l-istorja kollha terġa’ tibda ma’ kull talba.

3. Kif tuża l-kodiċi eżistenti ta' OpenAI ma' Grok?

Tweġiba: Billi tbiddel il-base_url għal https://api.x.ai/v1 u l-API key—il-kompatibbiltà tal-format timmaniġġja l-bqija, inkluż l-SDK ta’ OpenAI u l-Vercel AI SDK.

4. X'taqra fir-risposta u fl-użu?

Tweġiba: choices iġorr ir-risposti b’finish_reason; usage jiddettalja t-tokens, inkluż reasoning_tokens għal mudelli tar-raġunar—il-bażi għat-traċċar tal-ispejjeż.

5. Kif timmigra b'mod nadif lejn l-API tar-Risposti?

Tweġiba: Gradwalment: żviluppi ġodda fir-Risposti, endpoints eżistenti konvertiti wieħed wieħed b’test mill-ġdid tal-prompt—it-tqabbil taż-żewġ formati jiggwida l-konverżjoni.

Fhem l-antik, ibni għall-modern: il-pjan ta’ migrazzjoni gradwali tal-kors huwa l-mappa stradali tiegħek—mingħajr “big bang”.