Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Implementare gli Output Previsti in Python

Lezione 7 di 16 Aggiornata il 2 novembre 2026 Avanzato
In questa pagina
  1. Dal Concetto al Codice di Produzione
  2. Implementazione di Base
  3. Classe di Utilità per la Produzione
  4. Benchmark: Con e Senza Previsione
  5. Gestione degli Errori
  6. Vincoli da Conoscere
  7. Punti chiave

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 prediction si aggiunge semplicemente alla chiamata chat.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