Imirce Ghrádálach go dtí an API Freagartha
Ar an leathanach seo
Nuashonraithe 3 Samhain, 2026: Léirigh mapáil paraiméadar roimhe seo go gcoinníonn
max_tokensa ainm san API Freagartha; athraíonn tábla xAI é gomax_output_tokens, agus athraíonn ainmneacha na gcuntair úsáide freisin. Foinse: Comparáid le Críochnuithe Comhrá.
Cén fáth agus cathain le himirce a dhéanamh
Tá an pointe deiridh Críochnuithe Comhrá (Chat Completions) marcáilte mar sheanbhunaithe. Leanfaidh sé ag obair, ach ní chuirfear gnéithe nua leis. Má theastaíonn uirlisí taobh freastalaí (cuardach gréasáin, feidhmiú cód), stóráil comhrá, nó réasúnaíocht chriptithe do d’fheidhmchlár, éiríonn sé riachtanach imirce a dhéanamh go dtí an API Freagartha.
An dea-scéal: is féidir leis an imirce seo tarlú go grádálach. Ní gá duit gach rud a athscríobh ar fad ag an am céanna.
Céim 1: Sainaithin na gnéithe a úsáideann tú
Sula ndéanann tú imirce, déan stoc de na rudaí a úsáideann d’fheidhmchlár le Críochnuithe Comhrá:
# 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
Is iad glaonna bunúsacha agus sruthú (streaming) na cinn is simplí le himirce a dhéanamh orthu. Éilíonn glaonna feidhme (function calling) an formáid a oiriúnú. Oibríonn an radharc (vision) ar bhealach cosúil.
Céim 2: Imirce a dhéanamh ar ghlaonna bunúsacha
Leanann imirce ar ghla simplí an patrún seo:
# 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
Mapáil réimsí
Seo iad na príomhathruithe:
messagesle rólsystem→instructions(paraiméadar tiomnaithe)messagesle róluser→input(teaghrán simplí)response.choices[0].message.content→response.output_textmax_tokens→max_output_tokens, de réir tábla mapála xAI; coinníonntemperaturea ainmresponse.usage.prompt_tokensaguscompletion_tokens→input_tokensagusoutput_tokens(sonraí:input_tokens_details.cached_tokens,output_tokens_details.reasoning_tokens)
Céim 3: Imirce a dhéanamh ar chomhráite il-chasacha
Seo áit a ndéanann an API Freagartha rudaí níos simplí. In ionad stair a athchruthú le gach iarratas, slabhraíonn tú iad de réir 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
Tá an cód níos simplí agus ní gá duit an t-eagar teachtaireachtaí a bhainistiú de láimh a thuilleadh.
Céim 4: Leas a bhaint as gnéithe nua
Nuair a bheidh an imirce déanta agat, is féidir leat leas a bhaint as gnéithe atá ar fáil go heisiach san API Freagartha:
Cuardach gréasáin ionsuite
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
Stóráil freagartha
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)
Réasúnaíocht chriptithe
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
Straitéis imirce molta
In ionad gach rud a aistriú ag an am céanna, téigh i mbun oibre céim ar chéim:
- Sainaithin glaonna Críochnuithe Comhrá i do chód
- Aicmigh iad de réir castachta (bunúsach → sruthú → glaonna feidhme)
- Déan imirce ar dtús ar phointí deiridh nó ar ghnéithe nua (greenfield)
- Ansin déan imirce ar na glaonna atá ann cheana is simplí
- Coinnigh Críochnuithe Comhrá do chomhtháthuithe tríú páirtí a éilíonn é (LangChain, srl.)
Comhfhairsinge shealadach
Tá sé go hiomlán inghlactha an dá phointe deiridh a rith taobh le taobh a chéile le linn an aistrithe:
# 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
Ligeann an cur chuige seo duit aistriú go grádálach trí gach imirce a thástáil go haonair.
Príomhphointí
- Is féidir leis an imirce a bheith grádálach: ní gá gach rud a athscríobh ar fad ag an am céanna
- Na príomhathruithe:
messages→input/instructions,choices[0].message.content→output_text - Aistríonn comhráite il-chasacha ó eagar teachtaireachtaí go
previous_response_idsimplí - Tugann an API Freagartha rochtain ar ghnéithe eisiacha (cuardach gréasáin, stóráil, réasúnaíocht chriptithe)
- Rith an dá phointe deiridh taobh le taobh a chéile le linn an aistrithe agus déan imirce de réir castachta
Tástáil do chuid eolais
Tuigeadh an API seanbhunaithe agus ullmhaíodh an imirce.
1. Cad a chiallaíonn stádas seanbhunaithe agus gan staid de chuid Críochnuithe Comhrá?
Freagra: Fanann an pointe deiridh faoi thacaíocht ach ní fhorbraítear a thuilleadh é: gan staid, éilíonn sé an stair iomlán a athsheoladh le gach glao—is é an API Freagartha an bealach nua-aimseartha.
2. Cén ról a struchtúraíonn na teachtaireachtaí?
Freagra: system (agus developer), user, assistant—an creatlach, na hiarratais, na freagraí: tosaíonn an stair iomlán arís le gach iarratas.
3. Conas a úsáideann tú cód OpenAI atá ann cheana le Grok?
Freagra: Trí base_url a athrú go https://api.x.ai/v1 agus an eochair API a athrú—déanann comhoiriúnacht formáide an chuid eile, SDK OpenAI agus Vercel AI SDK san áireamh.
4. Cad a léann tú sa fhreagra agus san úsáid?
Freagra: Iompraíonn choices freagraí le finish_reason; míníonn usage na tokenanna, reasoning_tokens san áireamh do mhúnlaí réasúnaíochta—bunús le haghaidh rianaithe costais.
5. Conas a dhéanann tú imirce ghlan go dtí an API Freagartha?
Freagra: Go grádálach: forbairtí nua i bhFreagartha, pointí deiridh atá ann cheana a thiontú ceann ar cheann le hath-thástáil pras—treoraíonn comparáid idir an dá fhormáid an tiontú.
Tuig an seanbhunaithe, tóg don nua-aimseartha: is é plean imirce grádálaí an chúrsa do threoir—gan “big bang”.