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

Отговор и употреба

Урок 4 от 16 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Разберете какво връща API
  2. Пълна анатомия на отговора
  3. Масивът choices
  4. Стойности на finish_reason
  5. Обектът usage – Проследяване на разходите
  6. Съдържание на отговора
  7. Приложете го на практика
  8. Ключови изводи

Разберете какво връща 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 е от съществено значение за отстраняване на грешки и техническа поддръжка