Implementare gli Output Previsti in Python
In questa pagina
Dal Concetto al Codice di Produzione
Hai compreso il principio degli Output Previsti e i loro casi d’uso. Questa lezione fornisce codice Python completo, pronto per l’integrazione nelle tue applicazioni, inclusa la gestione degli errori e la misurazione delle prestazioni.
Implementazione di Base
Il pattern minimale richiede un solo parametro: prediction, dove passi il contenuto atteso. Tutto il resto della chiamata rimane invariato: stesso modello, stessi messaggi, stessa gestione della risposta. Questo rende la funzionalità facile da adottare e altrettanto semplice da rimuovere se le metriche non confermano il guadagno:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
source_code = """
import pandas as pd
def load_data(filepath):
df = pd.read_csv(filepath)
df['date'] = pd.to_datetime(df['date'])
df = df.dropna(subset=['value'])
return df
def compute_stats(df):
return {
'mean': df['value'].mean(),
'median': df['value'].median(),
'std': df['value'].std()
}
"""
prompt = (
"Add a 'separator' parameter to the load_data function "
"(default ',') and use it in read_csv. "
"Respond only with the complete modified code."
)
response = client.chat.complete(
model="codestral-latest",
messages=[
{"role": "user", "content": prompt},
{"role": "user", "content": source_code}
],
prediction={"type": "content", "content": source_code}
)
modified_code = response.choices[0].message.content
print(modified_code)
Classe di Utilità per la Produzione
L’incapsulamento offre qui vantaggi che vanno oltre la pulizia del codice: centralizza la decisione di abilitare o disabilitare la previsione. Questo è esattamente il tipo di impostazione che vuoi poter attivare o disattivare istantaneamente. Se un deployment rivela previsioni costantemente errate, puoi disabilitarle in un unico punto invece di cercare il parametro in tutto il tuo codebase:
from mistralai.client import Mistral
import time
from dataclasses import dataclass
@dataclass
class PredictionResult:
content: str
latency_ms: float
tokens_input: int
tokens_output: int
model: str
class PredictedEditor:
"""Editor di contenuti che utilizza gli Output Previsti."""
def __init__(self, api_key: str, model: str = "mistral-large-latest"):
self.client = Mistral(api_key=api_key)
self.model = model
def edit(
self,
original: str,
instruction: str,
system_prompt: str | None = None
) -> PredictionResult:
"""Modifica i contenuti con la previsione dell'output."""
messages = []
if system_prompt:
messages.append({"role": "system", "content": system_prompt})
messages.extend([
{"role": "user", "content": instruction},
{"role": "user", "content": original}
])
start = time.perf_counter()
response = self.client.chat.complete(
model=self.model,
messages=messages,
prediction={"type": "content", "content": original}
)
latency = (time.perf_counter() - start) * 1000
choice = response.choices[0]
return PredictionResult(
content=choice.message.content,
latency_ms=round(latency, 1),
tokens_input=response.usage.prompt_tokens,
tokens_output=response.usage.completion_tokens,
model=self.model
)
def edit_code(self, code: str, instruction: str) -> PredictionResult:
"""Scorciatoia per la modifica del codice."""
return self.edit(
original=code,
instruction=instruction,
system_prompt=(
"You are a programming assistant. "
"Respond only with the modified code, "
"without explanation or markdown."
)
)
def edit_text(self, text: str, instruction: str) -> PredictionResult:
"""Scorciatoia per la modifica del testo."""
return self.edit(
original=text,
instruction=instruction,
system_prompt=(
"You are a professional text editor. "
"Apply the requested modification while preserving "
"the style and structure of the original text. "
"Respond only with the modified text."
)
)
Utilizzo della Classe
editor = PredictedEditor(api_key="your-api-key", model="codestral-latest")
# Modifica codice
result = editor.edit_code(
code=my_python_file,
instruction="Replace all print() calls with logging.info() calls"
)
print(f"Latency: {result.latency_ms} ms")
print(f"Tokens: {result.tokens_input} in / {result.tokens_output} out")
print(result.content)
Benchmark: Con e Senza Previsione
Non saltare questo passaggio. Il guadagno offerto dagli Output Previsti dipende interamente dalla precisione delle tue previsioni, che a sua volta dipende dai tuoi dati. Nessuna cifra presente nella documentazione può sostituire la misurazione sui tuoi esempi specifici. Questo script confronta entrambe le modalità sugli stessi input, fornendoti la risposta in pochi secondi:
import statistics
def benchmark_prediction(
client, model, messages, prediction_content, runs=5
):
"""Confronta la latenza con e senza Output Previsto."""
times_normal = []
times_predicted = []
for _ in range(runs):
# Senza previsione
start = time.perf_counter()
client.chat.complete(model=model, messages=messages)
times_normal.append((time.perf_counter() - start) * 1000)
# Con previsione
start = time.perf_counter()
client.chat.complete(
model=model,
messages=messages,
prediction={"type": "content", "content": prediction_content}
)
times_predicted.append((time.perf_counter() - start) * 1000)
avg_normal = statistics.mean(times_normal)
avg_predicted = statistics.mean(times_predicted)
gain_pct = (1 - avg_predicted / avg_normal) * 100
return {
"without_prediction_ms": round(avg_normal, 1),
"with_prediction_ms": round(avg_predicted, 1),
"gain_percentage": round(gain_pct, 1),
"runs": runs
}
Gestione degli Errori
La gestione degli errori è qui diretta per una ragione strutturale: una previsione errata non costituisce un errore. Il modello la ignora e genera normalmente: perdi il guadagno in termini di latenza, mai la qualità. I veri casi limite si trovano altrove:
def safe_edit(editor, original, instruction):
"""Modifica con una gestione robusta degli errori."""
try:
result = editor.edit(original, instruction)
# Verifica che la risposta non sia vuota
if not result.content or len(result.content.strip()) < 10:
raise ValueError("Response too short or empty")
return result
except Exception as e:
# Fallback: riprova senza previsione
print(f"Predicted Output failed ({e}), falling back to standard...")
response = editor.client.chat.complete(
model=editor.model,
messages=[
{"role": "user", "content": instruction},
{"role": "user", "content": original}
]
)
return PredictionResult(
content=response.choices[0].message.content,
latency_ms=0,
tokens_input=response.usage.prompt_tokens,
tokens_output=response.usage.completion_tokens,
model=editor.model
)
Vincoli da Conoscere
Prima del deployment, integra tre punti nella tua code review. In primo luogo, il parametro n (generazioni multiple) è incompatibile con prediction. Se la tua pipeline richiede più completamenti, devi scegliere. In secondo luogo, la corrispondenza tra previsione e output è gestita dal modello indipendentemente dalla posizione del contenuto nella risposta: non devi preparare alcun allineamento. Infine, ed è ciò che rende la funzionalità sicura da deployare: una previsione errata non degrada mai la qualità della risposta; ti costa solo il guadagno in latenza. Lo scenario peggiore è semplicemente un ritorno alla velocità normale sui due modelli compatibili (mistral-large-latest e codestral-latest).
Punti chiave
- Il parametro
predictionsi aggiunge semplicemente alla chiamatachat.complete() - Incapsula la logica in una classe riutilizzabile per la produzione
- Misura sistematicamente il guadagno con un benchmark prima del deployment
- Prevedi un fallback senza previsione in caso di errori
- Una previsione errata non degrada la qualità, ma solo la latenza