Vastaus ja käyttö
Tällä sivulla
Ymmärrä, mitä API palauttaa
Useimmat kehittäjät, jotka ovat uusia API:n käytössä, lukevat vastauksesta vain yhden rivin – generoidun tekstin – ja jättävät kaiken muun huomiotta. Se on virhe. Jokainen /v1/chat/completions-kutsu palauttaa laajan JSON-objektin. Täältä löydät tiedot, joita tarvitset kustannusten seurantaan, typistyneen vastauksen havaitsemiseen ennen kuin se reaches käyttäjälle, sekä tietyn kutsun paikantamiseen, kun avaat tukipyynnön.
Vastauksen täydellinen anatomia
Aloitetaan metatiedoista. Nämä ovat kenttiä, joita tarkistat harvoin, mutta toivot niiden olevan lokissa sinä päivänä, kun incidentti tapahtuu:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is machine learning?"}],
max_tokens=500
)
# Access metadata
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")
id-kenttä on yksilöllinen tunniste, joka annetaan jokaiselle pyynnölle. Tämä on viite, jonka annat tekniselle tuelle, ja se, jonka avulla voit linkittää käyttäjän valituksen tiettyyn kutsuun lokeissasi. model-kenttä vahvistaa, mitä mallia todella käytettiin. Tämä on tärkeämpää kuin luuletkaan, kun kutsut -latest-aliasta ja käyttäytyminen muuttuu yön yli ilman, että koodissasi on tehty muutoksia.
choices-taulukko
Vastauksen ydin on choices-taulukossa. Oletusarvoisesti tämä taulukko sisältää yhden elementin. Siitä erotat sekä tekstin että tuomion siitä, miten generointi päättyi:
choice = response.choices[0]
# The generated message
print(choice.message.role) # "assistant"
print(choice.message.content) # The response text
# The index of this response in the array
print(choice.index) # 0
# The stop reason
print(choice.finish_reason) # "stop", "length", or "tool_calls"
Jos pyydät useita vastauksia käyttämällä n-parametria, jota käsittelemme oppitunnilla 15, choices sisältää useita elementtejä, ja indeksistä tulee jälleen merkityksellinen.
finish_reason-arvot
Tämä kenttä määrittää sovelluksesi luotettavuuden. Mahdollisia arvoja on kolme. stop ilmoittaa, että malli viimeisteli vastauksensa luonnollisesti. Tämä on normaali tapaus, jossa voit näyttää sisällön ilman varaumia. length tarkoittaa, että generointi katkaistiin max_tokens-rajoituksen vuoksi, joten vastaus on mahdollisesti epätäydellinen – yhteenveto, josta puuttuu johtopäätös, tai lista, joka pysähtyy seitsemänteen kohteeseen. Lopuksi tool_calls osoittaa, että malli pyytää ulkoisen työkalun suorittamista osana funktion kutsumista, ja pallo on nyt sinun kentälläsi.
Jokainen näistä tapauksista vaatii erilaista käsittelyä, joka sinun tulee kirjoittaa kerran ja lopullisesti:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a detailed report."}],
max_tokens=200
)
choice = response.choices[0]
if choice.finish_reason == "stop":
# Complete response — normal processing
result = choice.message.content
elif choice.finish_reason == "length":
# Truncated response — retry with more tokens or warn the user
print("Warning: The response was truncated.")
# Option: Retry with a higher max_tokens limit
# Option: Ask the model to continue
elif choice.finish_reason == "tool_calls":
# The model requests a tool call
for tool_call in choice.message.tool_calls:
print(f"Requested tool: {tool_call.function.name}")
Huomaa, että length-haara ei vain anna tekstin mennä läpi. Joko yrität uudelleen suuremmalla rajalla, pyydät mallia jatkamaan tai varoitat käyttäjää. Sitä, mitä et koskaan saa tehdä, on näyttää typistynyttä tekstiä ikään kuin se olisi täydellinen.
usage-objekti – seuraa kustannuksiasi
usage-kenttä laskee pyynnön kuluttamat tokenit erottaen syötteen ja tulosteen:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Tämä ero ei ole kosmeettinen. Mistral-malleilla on eri hinnat syötteelle ja tulosteelle. Ominaisuudella, joka lähettää pitkän kontekstin saadakseen takaisin kolme sanaa, on täysin erilainen kustannusprofiili kuin pitkällä luonnoksella, joka generoidaan lyhyestä kehotteesta. Laskenta vie vain muutaman rivin:
# Hypothetical rates per million tokens (check current pricing)
RATE_INPUT = 2.0 # $/M tokens input
RATE_OUTPUT = 6.0 # $/M tokens output
cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output
print(f"Cost of this call: ${cost_total:.6f}")
Yksi kutsu maksaa murto-osan sentistä, mikä on petollisen rauhoittavaa. Kerro tämä sovelluksen todellisella liikenteellä, ja kysymys kuuluu: mikä ominaisuus kuluttaa mitä? Vastataksesi tähän, kokoa käyttömittarit heti ensimmäisestä käyttöönotostasi alkaen. Lokita jokainen kutsu yhdessä sen ominaisuuden nimen kanssa, joka sen laukaisi:
import json
from datetime import datetime
def log_usage(response, endpoint_name: str):
"""Logs usage metrics for each API call."""
log_entry = {
"timestamp": datetime.utcnow().isoformat(),
"endpoint": endpoint_name,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"total_tokens": response.usage.total_tokens,
"finish_reason": response.choices[0].finish_reason,
"request_id": response.id
}
with open("api_usage.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# Usage
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")
Tällainen JSONL-tiedosto, jota tarkastellaan kahden viikon kuluttua, kertoo sinulle yksiselitteisesti, mikä näyttö tuotteessasi rasittaa laskua eniten – ja kuinka monta kutsua päättyy arvoon length.
Vastauksen sisältö
Avustajaviestin content-kenttä voi olla kahdessa muodossa, aivan kuten pyyntöpuolellakin:
# Simple form — string
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."
# Structured form — list of blocks (rare in standard chat)
# [{"type": "text", "text": "..."}]
Käytännössä tavallisissa Chat Completions -kutsuissa content on aina merkkijono. Jäsennelty muoto on varattu multimodaalisille vastauksille.
Ota käyttöön käytännössä
Kootaan kaikki tämä hyötyfunktioksi – sellaiseksi, jonka kopioit projektista toiseen. Se kokoaa viestit, tekee kutsun ja palauttaa sanakirjan, joka paljastaa sekä mittarit että tekstin:
from mistralai.client import Mistral
def chat_complete(
client: Mistral,
prompt: str,
system: str = "",
model: str = "mistral-large-latest",
max_tokens: int = 1000
) -> dict:
"""Chat Completions call with error handling and metrics."""
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
response = client.chat.complete(
model=model,
messages=messages,
max_tokens=max_tokens
)
return {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"tokens_in": response.usage.prompt_tokens,
"tokens_out": response.usage.completion_tokens,
"model": response.model,
"id": response.id
}
Avainasia on se, mitä funktio palauttaa: ei koskaan pelkkää tekstiä. Nostamalla finish_reason-arvon, token-määrät ja pyynnön tunnisteen kutsujalle teet yleisimmästä virheestä mahdotonta – katkaistun vastauksen kohtelemisen kelvollisena.
Keskeiset asiat
- Vastaus sisältää
choices(sisältö),usage(tokenit) ja metatiedot (id,model) - Tarkista aina
finish_reason–lengthtarkoittaa epätäydellistä vastausta usagelaskee syöte- ja tulostetokenit erikseen tarkkaa kustannusseurantaa varten- Määritä mittareiden lokitus heti ensimmäisestä tuotantokäyttöönotosta alkaen
id-kenttä on välttämätön vianetsinnässä ja teknisessä tuessa