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

Най-добри практики и обобщение

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

Обобщение на курса

Разгледахте пълния набор от механизми за структуриран изход, предлагани от Mistral API. Този финален урок обединява онова, което прави разликата в ежедневната работа: как да избирате между двата подхода, задължителните настройки, най-честите капани и какво да наблюдавате, след като преминете в продукционна среда.

Избор на подход

Четири въпроса са достатъчни, за да вземете решение, в следния ред. Имате ли дефинирана схема за изход? Ако отговорът е „не“, придържайте се към JSON Mode: вие сте в режим на проучване или прототипиране и фиксирането на модел на данни би било преждевременно. Ако отговорът е „да“, преминете към следващия въпрос.

Работите ли с Python или TypeScript? Ако е така, Custom Structured Outputs са готови за употреба чрез Pydantic или Zod. Ако не, JSON Mode с ръчна валидация остава вашият път.

В продукционна среда ли сте? Ако да, Custom Structured Outputs са задължителни, винаги. В противен случай JSON Mode е повече от достатъчен за прототипиране.

Променя ли се схемата често? Все още развиваща се схема прави JSON Mode по-практичен в началото, докато изискванията се стабилизират; фиксирана схема обосновава използването на Custom Structured Outputs и надеждността, която те носят.

Десетте златни правила

Първите пет се отнасят до начина, по който пишете заявките си. Винаги задавайте temperature=0 в продукционна среда: вариативността на температурата е враг на надеждността, а извличането на данни няма нужда от креативност.

# Production: deterministic
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    temperature=0  # Reproducibility
)

Винаги проверявайте finish_reason. Това е единственият индикатор, който ви предупреждава за съкратен отговор, преди да се опитате да го използвате.

if response.choices[0].finish_reason != "stop":
    # Response is truncated — increase max_tokens
    raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")

В JSON Mode винаги инструктирайте модела в промпта. Параметърът гарантира синтаксиса, но не и структурата: ваша отговорност е да посочите ключовете и техните типове.

# JSON Mode — the prompt MUST describe the structure
messages = [
    {
        "role": "system",
        "content": "Return JSON with keys: name (string), age (number), city (string)."
    },
    {"role": "user", "content": text}
]

В Custom mode документирайте полетата си. Точно описание струва повече от дълъг промпт и то пътува заедно със схемата и на двата езика.

class Product(BaseModel):
    name: str = Field(description="Commercial product name")
    price: float = Field(description="Price in EUR excluding tax, rounded to 2 decimals")
const ProductSchema = z.object({
  name: z.string().describe("Commercial product name"),
  price: z.number().describe("Price in EUR excluding tax, rounded to 2 decimals"),
});

Разделяйте контекста от съдържанието. Инструкциите живеят в системното съобщение, данните за обработка – в потребителското съобщение – никога обратното, иначе моделът ще обърка инструкцията с изходния текст.

messages = [
    {"role": "system", "content": "You are a data extractor. [Format instructions]"},
    {"role": "user", "content": "[Text to process — NO format instructions here]"}
]

Следващите две правила се отнасят до вашата предпазна мрежа. Внедрете механизъм за повторни опити (retry): никога не правете единично извикване без резервен план; повторният опит с обратна връзка е минималният шаблон в продукционна среда. И валидирайте извън схемата, тъй като схемата гарантира структурата, докато семантичната валидация – граници, съгласуваност, бизнес логика – остава ваша отговорност.

Последните три се отнасят до оркестрацията. Изберете правилния модел за правилния случай на употреба: mistral-large-latest за сложни задачи и извличане на множество полета, mistral-small-latest за проста класификация и основно извличане, ministral-8b-latest за висока честота и минимална латентност. Записвайте всяко извикване в продукционна среда, фиксирайки използвания модел, продължителността, finish_reason и резултата: без логове сте слепи. Накрая, не оптимизирайте прекалено рано промпта – започнете просто, измервайте, итерирайте; преждевременната оптимизация на промпта е често срещан капан, докато схемата и валидацията са истинските лостове.

Три скъпи капана

Първият е стойност на max_tokens, която е твърде ниска. JSON ще бъде съкратен при дълги отговори и грешката ще се прояви едва при големи документи, често след пускането в експлоатация.

# Dangerous — JSON will be truncated for long responses
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema,
    max_tokens=128  # Too low for a complex schema
)

Задайте max_tokens въз основа на очаквания размер на вашия изход: една фактура с 20 реда изисква повече токени от проста класификация.

Вторият е температура, различна от нула, което прави резултатите ви невъзпроизводими без никаква полза за задача по извличане.

# Dangerous in production — non-reproducible results
response = client.chat.parse(
    ...,
    temperature=0.7  # Unnecessary variation for extraction
)

Третият е рефлексът да използвате един единствен модел. Не използвайте mistral-large за всичко: двоичната класификация не изисква най-мощния модел и ministral-8b ще свърши работата 5 пъти по-бързо на по-ниска цена.

Какво да наблюдавате

Четири метрики показват здравето на вашия конвейер. Степента на успех измерва процента извиквания, които връщат валиден обект от първия опит; степента на повторни опити – процента извиквания, които са се нуждаели от втори шанс. Латентността P50/P95 дава медианното време за отговор и 95-тия перцентил, което е по-показателно от средната стойност. Разходите за извличане, изразени в консумирани токени на извикване, държат сметката под контрол.

Върху тези метрики няколко прага за предупреждение се утвърждават добре: степен на успех под 95% оправдава жълто предупреждение, под 85% – червено предупреждение; P95 латентност, по-голяма от 10 секунди, налага разследване; а отворен прекъсвач (circuit breaker) изисква незабавно предупреждение.

Напредък

Четири направления естествено разширяват този курс. Извикването на функции (Function calling) използва структурирани изходи за захранване на извиквания на функции в агент. Стриймингът ви позволява да получавате структурирания изход прогресивно, което е важно за дълги отговори. Дообучението (Fine-tuning) адаптира модел на Mistral, за да подобри качеството на извличане върху вашите специфични данни. Оценяването (Evaluation) накрая се състои в създаването на автоматизирана рамка, базирана на златен набор от данни и метрики – това е онова, което ще ви каже дали промяна в промпта действително подобрява нещата.

Пълен конвейер

Следният код обединява практиките от курса в един поток: схема, описана поле по поле, валидатор, който отхвърля резултати извън границите, модел, оразмерен спрямо задачата, temperature=0, изричен max_tokens, проверка на finish_reason и записване в логове и за двата възможни изхода.

from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time

logger = logging.getLogger("pipeline")

class CustomerFeedback(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    score: float = Field(description="Score between -1.0 and 1.0")
    category: str = Field(description="product, service, delivery, price, or other")
    action_required: bool = Field(description="True if action is required")
    summary: str = Field(description="One-sentence summary")

    @field_validator("score")
    @classmethod
    def score_in_range(cls, v):
        if not -1.0 <= v <= 1.0:
            raise ValueError(f"Score out of bounds: {v}")
        return v

def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
    start = time.time()
    try:
        response = client.chat.parse(
            model="mistral-small-latest",
            messages=[
                {"role": "system", "content": "Analyze customer feedback."},
                {"role": "user", "content": text}
            ],
            response_format=CustomerFeedback,
            temperature=0,
            max_tokens=256
        )
        assert response.choices[0].finish_reason == "stop"
        result = response.choices[0].message.parsed
        logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
        return result
    except Exception as e:
        logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
        raise

Около тридесет реда и вие разполагате с компонент, който може безопасно да бъде включен в средата на една система: точно това правят възможните структурираните изходи.

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

  • Използвайте Custom Structured Outputs в продукционна среда, а JSON Mode за прототипиране
  • temperature=0, проверката на finish_reason и повторните опити са задължителни
  • Изберете модела въз основа на сложността на задачата и бюджета
  • Наблюдавайте степента на успех, латентността и разходите
  • Започнете просто, измервайте, след това оптимизирайте

Проверете знанията си

JSON Mode, схеми, повторни опити: контролиран ли е структурираният изход?

1. JSON Mode срещу Custom Structured Outputs: каква е разликата?

Отговор: JSON Mode гарантира синтактично валиден JSON; Custom Structured Outputs допълнително налагат вашата точна схема – полета, типове, структура: пълният договор.

2. Какво предоставя client.chat.parse() с Pydantic?

Отговор: Пълния цикъл: схемата на Pydantic декларира структурата, API ограничава генерирането, а отговорът пристига вече валидиран и типизиран като Python обект – нула ръчно парсиране.

3. А от страна на TypeScript?

Отговор: Същият комфорт със Zod: схемата на Zod дефинира и валидира структурата – един източник на истина за генерирането и типизирането.

4. Какво да правите, когато изходът не спазва схемата?

Отговор: Валидирайте систематично и планирайте стратегия за повторни опити: поискайте отново с грешката в контекста или деградирайте грациозно – никога сляпо доверие в изхода.

5. Кога структурираният изход е незаменим?

Отговор: Веднага щом програма консумира отговора без човешки преглед: извличане, интеграции, конвейери – форматът престава да бъде любезност, той става интерфейс.

Декларирана схема, ограничено генериране, валидация на изхода: триадата, която прави ИИ включваем в реален софтуер.