Отговор и употреба
На тази страница
Разберете какво връща API
Повечето разработчици, които тепърва започват работа с API, прочитат само един ред от отговора – генерирания текст – и игнорират всичко останало. Това е грешка. Всяко обаждане до /v1/chat/completions връща богат JSON обект. Тук ще откриете данните, необходими за проследяване на разходите, откриване на съкратен отговор, преди той да стигне до потребителя, и идентифициране на конкретно обаждане при подаване на сигнал за поддръжка.
Пълна анатомия на отговора
Нека започнем с метаданните. Това са полетата, които рядко проверявате, но ще съжалявате, че не сте ги записали в деня, в който възникне инцидент:
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 е уникален идентификатор, присвоен на всяка заявка. Това е референцията, която ще предоставите на техническата поддръжка, и тази, която Ви позволява да свържете оплакване от потребител с конкретно обаждане във Вашите логове. Полето model потвърждава кой модел действително е използван. Това е по-важно, отколкото може да си мислите, когато извиквате псевдоним -latest и поведението се променя за една нощ без никакви промени във Вашия код.
Масивът choices
Сърцето на отговора се намира в choices. По подразбиране този масив съдържа един единствен елемент. От него извличате както текста, така и присъдата за това как е приключило генерирането:
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"
Ако поискате множество отговори, използвайки параметъра n, който ще разгледаме в урок 15, choices ще съдържа множество елементи и индексът отново ще придобие смисъл.
Стойности на finish_reason
Това поле определя надеждността на Вашето приложение. Има три възможни стойности. stop сигнализира, че моделът е завършил отговора си естествено. Това е нормалният случай, при който можете да покажете съдържанието без резерви. length означава, че генерирането е било прекъснато от max_tokens, така че отговорът е потенциално непълен – обобщение, на което липсва заключението, или списък, който спира на седмия елемент. Накрая, tool_calls показва, че моделът иска изпълнението на външен инструмент като част от извикването на функции и топката сега е във Ваше поле.
Всеки от тези случаи изисква различно обработване, което трябва да напишете веднъж завинаги:
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}")
Забележете, че клонът length просто не пропуска текста. Или правите повторен опит с по-висок лимит, молимодела да продължи, или предупреждавате потребителя. Това, което никога не трябва да правите, е да показвате съкратен текст, сякаш е пълен.
Обектът usage – Проследяване на разходите
Полето usage брои токените, консумирани от заявката, като разделя входните от изходните:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Това разграничение не е козметично. Моделите на Mistral имат различни тарифи за вход и изход. Функция, която изпраща дълъг контекст, за да получи три думи в замяна, има напълно различен профил на разходите в сравнение с дълъг чернова, генерирана от кратък подканващ текст. Изчислението отнема само няколко реда:
# 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}")
Едно обаждане струва част от цента, което е фалшиво успокояващо. Умножете това по реалния трафик на едно приложение и въпросът става: коя функция консумира какво? За да отговорите на това, агрегирайте метриките за употреба още от първото си внедряване. Записвайте всяко обаждане заедно с името на функцията, която го е задействала:
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")
Такъв JSONL файл, прегледан след две седмици, ще Ви каже без двусмислие кой екран във Вашия продукт тежи най-много във фактурата – и колко обаждания завършват с length.
Съдържание на отговора
Полето content на съобщението на асистента може да приеме две форми, точно както от страната на заявката:
# 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": "..."}]
На практика, за стандартни обаждания към Chat Completions, content винаги е низ. Структурираната форма е запазена за мултимодални отговори.
Приложете го на практика
Нека съберем всичко това в една спомагателна функция – тази, която ще копирате от проект в проект. Тя сглобява съобщенията, прави обаждането и връща речник, който излага както метриките, така и текста:
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
}
Ключовият момент е какво връща функцията: никога само текста. Като издигате finish_reason, броя на токените и ID на заявката до callers, Вие правите най-честата грешка невъзможна – третирането на съкратен отговор като валиден.
Ключови изводи
- Отговорът съдържа
choices(съдържание),usage(токени) и метаданни (id,model) - Винаги проверявайте
finish_reason–lengthозначава непълен отговор usageброи входните и изходните токени поотделно за точно проследяване на разходите- Настройте записване на метрики още от първото си производствено внедряване
- Полето
idе от съществено значение за отстраняване на грешки и техническа поддръжка