AI Prompt Engineering · Lezione

Analisi delle cause principali dei problemi nei prompt

Individui se il problema riguarda il contesto, le istruzioni, il formato o le capacità del modello

Analisi delle cause principali dei problemi nei prompt è una lezione AI Prompt Engineering gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Prompt Engineering, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Prompt Engineering include 4 lezioni in totale.

Perché l'analisi delle cause principali è importante

Quando un prompt fallisce, le possibili cause sono molteplici. Modificare casualmente la formulazione fa perdere tempo e può correggere il sintomo senza risolvere la causa principale, causando lo stesso errore con input leggermente diversi.

L'analisi delle cause principali (RCA) è un processo sistematico per isolare il motivo specifico per cui un prompt fallisce, in modo che la correzione risolva il problema effettivo.

Le quattro categorie delle cause principali

Ogni errore del prompt può essere ricondotto a una delle quattro cause principali:

Problema di contesto: il modello non dispone delle informazioni necessarie per rispondere correttamente
Ambiguità dell'istruzione: l'istruzione ammette più interpretazioni valide e il modello ha scelto quella sbagliata
Conflitto di formato: due parti del prompt forniscono istruzioni di formattazione contraddittorie
Limite delle capacità del modello: l'attività richiede capacità di ragionamento o conoscenze che questo modello non è in grado di gestire in modo affidabile

Causa principale 1: problema di contesto

Un problema di contesto si verifica quando il modello risponde in modo errato perché il prompt non fornisce le informazioni necessarie. Il modello colma la lacuna con i dati di addestramento, che potrebbero essere obsoleti, errati o frutto di un'allucinazione.

Test: fornisca direttamente nel prompt le informazioni mancanti e verifichi se la risposta migliora. Se migliora, la correzione consiste nell'aggiungere contesto, ad esempio tramite il recupero RAG.

# Failing prompt — no context
prompt_v1 = 'What is the current price of our Pro plan?'

# Context problem test: inject the information
prompt_v2 = '''
Our pricing (as of today):
- Free: $0/month
- Pro: $19/month
- Enterprise: $99/month

Question: What is the current price of our Pro plan?
'''
# If v2 succeeds and v1 fails -> root cause is context problem

Causa principale 2: ambiguità dell'istruzione

L'ambiguità dell'istruzione si verifica quando il prompt può essere ragionevolmente interpretato in più modi e il modello sceglie l'interpretazione sbagliata.

Esempio: «Riassumi brevemente»: che cosa significa «brevemente»? Una frase, un paragrafo o tre punti elenco? Il modello deve indovinare. Test: sostituisca la frase ambigua con una specifica precisa e verifichi se l'errore viene risolto.

# Ambiguous
prompt_ambiguous = 'Summarize the following article briefly.'

# Precise — ambiguity removed
prompt_precise = (
    'Summarize the following article in exactly 2 sentences. '
    'Do not exceed 50 words. Output only the summary, nothing else.'
)

# Test: if precise version succeeds, root cause was ambiguity
# Fix: replace vague qualifiers with exact specifications

Causa principale 3: conflitto di formato

Un conflitto di formato si verifica quando due parti del prompt forniscono istruzioni contraddittorie. Il modello deve sceglierne una e ignorare l'altra, di solito seguendo l'istruzione più recente o più evidente.

Esempio: il prompt di sistema dice «rispondi in testo semplice», mentre il messaggio dell'utente dice «usa markdown». Il modello può seguire l'una o l'altra istruzione, in modo incoerente.

# Format conflict example
system_prompt = 'You are a helpful assistant. Always respond in plain text without any formatting.'

user_message = 'List the top 5 benefits of exercise. Use markdown bullet points.'

# The model faces a conflict: plain text vs markdown.
# Detection: if output format is inconsistent across runs, look for conflicting instructions.

# Fix: ensure all format instructions agree. Move format to system prompt only.
system_prompt_fixed = (
    'You are a helpful assistant. '
    'Always respond using markdown bullet points for lists.'
)

Causa principale 4: limite delle capacità del modello

Si verifica un errore dovuto a un limite delle capacità quando l'attività supera realmente ciò che il modello è in grado di fare in modo affidabile. Questo caso è diverso dagli altri tre: nessuna modifica al prompt lo risolverà completamente.

Segnali: il tasso di errore è elevato anche con istruzioni chiare e contesto completo. Soluzioni: utilizzare un modello più potente, suddividere l'attività in passaggi più semplici oppure aggiungere un passaggio di verifica.

# Capability limit test: try the same task on different models
models = ['gpt-4o-mini', 'gpt-4o', 'gpt-4o-2024-11-20']
results = {}

for model in models:
    resp = client.chat.completions.create(
        model=model,
        messages=[{'role': 'user', 'content': complex_reasoning_prompt}]
    )
    results[model] = evaluate(resp.choices[0].message.content)

# If accuracy improves with more capable models -> capability limit
for model, score in results.items():
    print(f'{model}: {score:.0%} accuracy')

Il metodo dell'isolamento

Per identificare la causa principale attiva, utilizzi un isolamento sistematico:

Esegua il prompt che genera l'errore e classifichi il tipo di errore (risposta errata, formato, ecc.)
Aggiunga informazioni → se il problema si risolve: problema di contesto
Chiarisca le istruzioni → se il problema si risolve: ambiguità
Verifichi l'eventuale presenza di contraddizioni → se il problema si risolve: conflitto di formato
Passi a un modello più avanzato → se il problema si risolve: limite delle capacità del modello

Dovrebbe essere necessaria una sola correzione. Se ne servono diverse, erano presenti più cause principali.

def rca_test(base_prompt, test_input, expected_output):
    results = {}

    # Test 1: base (failing) prompt
    results['base'] = run_and_evaluate(base_prompt, test_input, expected_output)

    # Test 2: add context
    results['with_context'] = run_and_evaluate(
        base_prompt + '\nContext: ' + get_context(test_input),
        test_input, expected_output
    )

    # Test 3: clarify instructions
    results['clarified'] = run_and_evaluate(
        clarify(base_prompt), test_input, expected_output
    )

    for name, passed in results.items():
        print(f'{name}: {"PASS" if passed else "FAIL"}')

Esclusione e conferma

L'RCA segue due modalità:

Esclusione: escludere le cause che NON sono responsabili (verificare ogni ipotesi e osservare quale NON modifica l'output)
Conferma: identificare la causa che, una volta corretta, risolve sistematicamente l'errore con più input di test

La conferma richiede almeno 3 input di test. Una correzione che funziona con un solo input ma non con gli altri non ha risolto la causa principale: potrebbe aver risolto solo un sintomo.

def confirm_root_cause(fix_fn, test_cases, threshold=0.9):
    '''fix_fn: a function that takes a prompt and returns a fixed prompt'''
    passed = 0
    for case in test_cases:
        fixed_prompt = fix_fn(case['prompt'])
        result = run_and_evaluate(fixed_prompt, case['input'], case['expected'])
        if result:
            passed += 1

    pass_rate = passed / len(test_cases)
    print(f'Fix pass rate: {pass_rate:.0%}')
    if pass_rate >= threshold:
        print('Root cause CONFIRMED — fix is reliable.')
    else:
        print('Root cause NOT confirmed — failure has multiple causes.')

Documentare la causa principale

Dopo aver identificato la causa principale, la documenti nel registro delle modifiche al prompt. Includa:

Tipo di errore osservato
Categoria della causa principale
Ipotesi verificata
Prova (quale test ha avuto esito positivo dopo la correzione)
La modifica specifica apportata al prompt

In questo modo si evita che altri sviluppatori debbano analizzare nuovamente lo stesso errore e si facilita il riconoscimento di schemi ricorrenti tra i prompt.

rca_record = {
    'prompt_id': 'summarize_v3',
    'failure_type': 'wrong_format',
    'root_cause': 'format_conflict',
    'hypothesis': 'System prompt said plain text, user message asked for markdown',
    'evidence': 'Removing markdown instruction from user message resolved failure on 8/8 test cases',
    'fix_applied': 'Moved all format instructions to system prompt; removed format instructions from user template',
    'fix_date': '2024-11-15'
}

Errore comune: correggere la causa sbagliata

L'errore più comune nell'RCA consiste nel correggere il sintomo invece della causa. Esempio:

Sintomo: il modello restituisce JSON con un testo introduttivo aggiuntivo
Correzione errata: aggiungere una fase di post-elaborazione per rimuovere il testo dall'output
Causa principale effettiva: nel prompt non è presente alcuna istruzione sul formato e il modello utilizza per impostazione predefinita uno stile conversazionale
Correzione corretta: aggiungere l'istruzione esplicita «Restituisca solo JSON valido. Nessun altro testo.»

Le soluzioni improvvisate di post-elaborazione accumulano debito tecnico. Le correzioni della causa principale sono durature.

RCA degli errori intermittenti

Alcuni errori sono intermittenti: il prompt funziona nell'80% dei casi ma fallisce nel 20%. Sono più difficili da diagnosticare perché una singola esecuzione del prompt produce una risposta corretta.

Approccio: esegua il prompt 10–20 volte con lo stesso input. Se il tasso di errore è diverso da zero, il prompt ha una causa principale probabilistica, generalmente l'ambiguità delle istruzioni o un valore elevato di temperature. Soluzione: renda l'istruzione più specifica oppure riduca temperature.

def measure_failure_rate(prompt, test_input, expected, runs=20):
    failures = 0
    for _ in range(runs):
        resp = client.chat.completions.create(
            model='gpt-4o',
            messages=[{'role': 'user', 'content': prompt + '\n' + test_input}],
            temperature=0.7
        )
        if not evaluate(resp.choices[0].message.content, expected):
            failures += 1
    print(f'Failure rate: {failures}/{runs} = {failures/runs:.0%}')

Verifica delle conoscenze

Un prompt richiede una risposta JSON, ma occasionalmente restituisce JSON preceduto da un'introduzione conversazionale come «Certamente! Ecco il JSON:». Dopo aver aggiunto «Restituisca solo JSON valido. Nessun altro testo.», l'errore scompare. Qual era la causa principale?

Riepilogo: analisi della causa principale

Le quattro categorie di cause principali degli errori dei prompt:

Problema di contesto: al modello mancano informazioni necessarie — soluzione: aggiungere contesto tramite RAG o iniezione diretta
Ambiguità delle istruzioni: istruzione vaga con più interpretazioni possibili — soluzione: aggiungere precisione
Conflitto di formato: istruzioni di formattazione contraddittorie — soluzione: riunirle nel system prompt
Limite delle capacità del modello: l'attività supera le capacità del modello — soluzione: utilizzare un modello più avanzato o scomporre l'attività

Utilizzi l'isolamento sistematico per verificare ogni ipotesi. Confermi la correzione con più casi di test. Documenti i risultati. Prossima lezione: debugging sistematico mediante ricerca binaria.

Domande Frequenti

La lezione «Analisi delle cause principali dei problemi nei prompt» è gratuita?

Sì — il testo completo di «Analisi delle cause principali dei problemi nei prompt» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Prompt Engineering, passa a CoddyKit PRO. Il corso AI Prompt Engineering include 4 lezioni in totale.

Cosa imparerò in «Analisi delle cause principali dei problemi nei prompt»?

Individui se il problema riguarda il contesto, le istruzioni, il formato o le capacità del modello Eserciti AI Prompt Engineering con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Prompt Engineering?

Non è richiesta alcuna esperienza precedente. AI Prompt Engineering su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Analisi delle cause principali dei problemi nei prompt»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Prompt Engineering?

Sì. Ogni lezione AI Prompt Engineering include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Diagnosticare output imprevisti
Analisi delle cause principali dei problemi nei prompt
Approccio sistematico al debugging
Strategie di logging e documentazione

← Torna a AI Prompt Engineering