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

Анти-шаблони при работа с API

Урок 12 от 16 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Грешки, които струват скъпо в продукционна среда
  2. Третиране на съкратен отговор като пълен
  3. Позволяване на неограничен растеж на историята на разговора
  4. Приемане, че мрежата винаги отговаря
  5. Искайте от модела да прави това, което не може
  6. Разполагане без оставяне на следа
  7. Процедура за отстраняване на грешки
  8. Ключови изводи

Грешки, които струват скъпо в продукционна среда

След като разгледахме най-добрите практики, е време да обърнем внимание на обратната страна. Анти-шаблоните по-долу са най-честите капани при използването на Chat Completions API и всички те имат една неприятна черта: не се проявяват по време на разработка. От десет тестови заявки всичко работи перфектно. Проблемите избухват в продукционна среда, причинявайки неочаквани разходи, несвързани отговори, висока латентност или, което е по-лошо – изтичане на чувствителни данни.

Третиране на съкратен отговор като пълен

Най-честата грешка е игнорирането на finish_reason. Поисквате договор, получавате някакъв текст, запазвате го в базата данни: освен че max_tokens=100 е прекъснало генерирането насред клауза, и никой не забелязва това, докато клиентът не подпише. Решението отнема три реда код и трябва да стане рефлекс.

# ЛОШО — без проверка
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Draft a complete contract."}],
    max_tokens=100  # Твърде кратко за договор!
)
contract = response.choices[0].message.content  # Потенциално съкратено!

# ДОБРЕ — системна проверка
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Draft a complete contract."}],
    max_tokens=4000
)

if response.choices[0].finish_reason == "length":
    print("WARNING: Response truncated, increase max_tokens")
else:
    contract = response.choices[0].message.content

Позволяване на неограничен растеж на историята на разговора

Вторият капан се задейства бавно. Цикъл на чат, който изпраща цялата история на разговора при всяко завъртане, работи перфектно за първите десет обмена, удвоява разходите до двадесетия и в крайна сметка надвишава лимита на контекстния прозорец до стотния – като сметката следва същата крива. Решението е да запазите системното подканване (което не подлежи на преговори) и да задържите само последните N съобщения.

# ЛОШО — историята расте безкрайно
conversation = []
while True:
    user_input = input("You: ")
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=conversation  # 100 завъртания = хиляди токени!
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})

# ДОБРЕ – плъзгащ се прозорец с изрязване
MAX_MESSAGES = 20

def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
    """Запазва системното подканване + последните N съобщения."""
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    if len(history) > max_messages:
        history = history[-max_messages:]

    return system + history

Приемане, че мрежата винаги отговаря

Едно голо API извикване предполага, че нищо няма да се обърка: няма изчаквания, няма 429 грешки, няма 500 грешки. В продукционна среда и трите се случват, а третата се случва в най-неподходящия момент. Обърнете внимание на разликата в кода: за 429 е оправдано експоненциалното отлагане (backoff), за грешка на сървъра е нужна секунда търпение, но грешка от страна на клиента като 400 или 401 никога не трябва да се повтаря – вашият ключ няма да стане валиден при третия опит; само ще забавите диагностицирането.

# ЛОШО — без обработка на грешки
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}]
)
# Срива се при timeout, 429, 500...

# ДОБРЕ — повторен опит с backoff
from mistralai.client.errors import SDKError
import time

def safe_complete(client, messages, max_retries=3, **kwargs):
    """API извикване с повторен опит и експоненциално отлагане."""
    for attempt in range(max_retries):
        try:
            return client.chat.complete(messages=messages, **kwargs)
        except SDKError as e:
            if e.status_code == 429:
                wait = 2 ** attempt
                print(f"Rate limit hit, waiting {wait}s...")
                time.sleep(wait)
            elif e.status_code >= 500:
                time.sleep(1)
            else:
                raise  # Грешка от клиента (400, 401) — не повтаряйте
    raise Exception("Failed after 3 attempts")

Искайте от модела да прави това, което не може

Тук се събират три анти-шаблона. Първият е субективният език: „кратко“, „много“, „интересно“ не се отнасят до нищо проверимо и моделът ще решава различно от едно извикване до друго. Заменете всяко прилагателно с число или наблюдаем критерий.

# ЛОШО — субективно, неизмеримо
"Write a short summary."           # Кратко = 1 изречение? 1 абзац?
"Give many examples."              # Много = 3? 10? 50?
"Answer in an interesting way."    # Интересно по какви критерии?

# ДОБРЕ — обективни критерии
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."

Вторият е оставянето на модела да брои. LLM са печално известни с лошото си броене на думи, символи и елементи: искането за „точно 280 символа“ ще произведе текст от 240 или 310. Броенето принадлежи на вашето приложение, а не на модела.

# ЛОШО — моделът не може да брои точно
"Write exactly 280 characters for a tweet."

# ДОБРЕ — броене от страна на приложението
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Write a tweet about AI in France."}],
    max_tokens=100
)

tweet = response.choices[0].message.content
if len(tweet) > 280:
    tweet = tweet[:277] + "..."

print(f"Tweet ({len(tweet)} chars): {tweet}")

Третият попада в същото семейство: числови скали. „Оценете от 1 до 5“ предполага, че моделът има стабилно представяне за разликата между 3 и 4, което не е вярно. Вербална скала, където всяка стъпка е дефинирана от критерий, води до много по-възпроизводими оценки.

# ЛОШО — моделите тълкуват числовите скали зле
"Rate the quality of this text from 1 to 5."

# ДОБРЕ — вербална скала с дефиниции
"""Rate the quality of this text according to the following scale:
- EXCELLENT: Clear, well-structured, no errors
- GOOD: Generally correct, minor improvements possible
- AVERAGE: Understandable but lacks structure or contains errors
- POOR: Difficult to understand, significant errors
- VERY POOR: Incomprehensible or off-topic

Respond only with the label in uppercase."""

Разполагане без оставяне на следа

Последният анти-шаблон е най-незабележим: извикване на API, връщане на съдържанието и запазване на нищо. В деня, в който потребител съобщи за абнормен отговор, вие нямате нито ID на заявката, нито действителния обслужван модел, нито потреблението на токени. Структурираното регистриране (logging) за всяко извикване струва няколко милисекунди и прави разследването възможно.

# ЛОШО — без следа
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)
return response.choices[0].message.content

# ДОБРЕ — структурирано регистриране
import logging
import json

logger = logging.getLogger("mistral_api")

def logged_complete(client, messages, **kwargs):
    """API извикване със структурирано регистриране."""
    response = client.chat.complete(messages=messages, **kwargs)

    logger.info(json.dumps({
        "request_id": response.id,
        "model": response.model,
        "prompt_tokens": response.usage.prompt_tokens,
        "completion_tokens": response.usage.completion_tokens,
        "finish_reason": response.choices[0].finish_reason
    }))

    return response

Процедура за отстраняване на грешки

Когато отговорът не отговаря на очакванията Ви, изкушението е да пренапишете подканването. Вместо това, започнете с пет механични проверки, по ред: Дали отговорът е пълен? Отговори ли правилният модел? Колко токена са консумирани? Дали отговорът е празен? Дали съотношението изход/вход е правдоподобно? Съотношение под 1% при голямо подканване почти винаги сигнализира, че моделът е отказал да обработи заявката, а не я е обработил неправилно.

def debug_response(response):
    """Контролен списък за отстраняване на грешки при неочаквани отговори."""
    choice = response.choices[0]

    # 1. Дали отговорът е пълен?
    if choice.finish_reason == "length":
        print("ISSUE: Response truncated — increase max_tokens")

    # 2. Използван ли е правилният модел?
    print(f"Model: {response.model}")

    # 3. Колко токена са консумирани?
    print(f"Input tokens: {response.usage.prompt_tokens}")
    print(f"Output tokens: {response.usage.completion_tokens}")

    # 4. Дали отговорът е празен?
    if not choice.message.content or not choice.message.content.strip():
        print("ISSUE: Empty response")

    # 5. Подозрително съотношение вход/изход?
    ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
    if ratio < 0.01:
        print(f"WARNING: Very low output/input ratio ({ratio:.4f})")

Ключови изводи

  • Винаги проверявайте finish_reason, за да откриете съкращаване
  • Ограничете историята на разговора с плъзгащ се прозорец
  • Внедрете повторен опит с експоненциално отлагане за мрежови грешки
  • Използвайте обективни, измерими критерии във вашите подканвания
  • Никога не оставяйте модела да брои – валидирайте от страна на приложението
  • Регистрирайте всяко API извикване в продукционна среда за отстраняване на грешки и проследяване на разходите