Най-добри практики и обобщение
На тази страница
Обобщение на курса
Разгледахте пълния набор от механизми за структуриран изход, предлагани от 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. Кога структурираният изход е незаменим?
Отговор: Веднага щом програма консумира отговора без човешки преглед: извличане, интеграции, конвейери – форматът престава да бъде любезност, той става интерфейс.
Декларирана схема, ограничено генериране, валидация на изхода: триадата, която прави ИИ включваем в реален софтуер.