Tutorial API Grok 4.7: crea un revisore AI per progetti di circuiti

Uno schema elettrico è un diagramma che mostra come sono collegati i componenti elettronici. Revisionarlo significa verificare se i componenti e i loro valori soddisfano i requisiti di progetto. L’alimentatore può fornire corrente a sufficienza? Il processore può leggere tutta l’uscita del sensore? Le risposte arrivano dallo schema, dai datasheet dei componenti e da qualche calcolo.

Volevo capire se Grok 4.7 potesse completare l’intera revisione. La guida a Grok 4.7 dice che il modello è stato addestrato per compiti più lunghi e per controllare il proprio lavoro con maggiore attenzione. Un circuito, inoltre, ci dà numeri che il normale codice Python può verificare, quindi non serve un altro modello AI per giudicare il risultato.

Per l’esperimento, ho costruito EnviroNode Rev A, una piccola scheda sensore alimentata via USB, inserendo tre difetti nel progetto. A Grok non viene detto quanti difetti esistono. Deve trovarli, supportare ogni rilievo con la documentazione dei componenti, proporre correzioni e inviare i valori corretti ai controlli Python.

Non ti serve un background in ingegneria elettronica per seguire. Spiego ogni regola del circuito quando compare per la prima volta. Imparerai a:

• Inviare un’immagine dello schema a Grok 4.7 tramite la Responses API

• Allegare datasheet con la Files API e lasciare che Grok li cerchi

• Verificare i calcoli con code execution e i limiti con la ricerca web

• Dare a Grok una funzione locale verify_design() che decide pass o fail

• Mantenere una conversazione lunga e ricca di documenti entro il limite di contesto del modello

• Restituire un formato di revisione coerente, poi confrontare i livelli di ragionamento

La stessa scheda rimane in vista dalla prima revisione dell’immagine fino al controllo finale in Python.

TL;DR

Grok 4.7 ha identificato ogni difetto inserito una volta ottenuti i datasheet, e il progetto corretto ha superato i controlli Python. Questo dice qualcosa su questi tre difetti, non sulla revisione dei circuiti in generale.

• Senza documenti, Grok ha rifiutato di indovinare: l’immagine da sola ha dato un difetto confermato, mentre i limiti del regolatore e dell’ADC (analog-to-digital converter) sono finiti sotto “richiede prove”.
• I datasheet hanno trasformato il sospetto in prova: ogni rilievo ha citato un valore documentale, senza segnalare componenti corretti come errati.
• Turn ricchi di file possono esaurire il contesto a lungo termine: dopo ricerche PDF ripetute, una continuazione ha superato la finestra da 500K; il loop corretto compatta prima del turno successivo.
• Low ha superato il verificatore ma ha esposto un punto cieco: i suoi valori del filtro hanno soddisfatto i controlli scritti lasciando non testati il carico capacitivo e il comportamento di assestamento.

Questa è una scheda piccola, non un benchmark. Una scheda con una dozzina di datasheet creerà un contesto più ampio e potrebbe produrre risultati diversi.

Che cos’è la Grok 4.7 API?

L’API Grok 4.7 offre alle app Python input di testo e immagini, output testuale e una finestra di contesto da 500.000 token tramite l’ID modello grok-4.7. La guida ufficiale elenca i livelli di ragionamento low, medium, high (predefinito) e xhigh; il ragionamento non può essere disattivato. L’API supporta anche function calling, output strutturati, ricerca web, ricerca su X ed esecuzione di codice.

La nostra panoramica su Grok 4.7 copre il lancio e i benchmark. SpaceXAI etichetta Chat Completions come legacy, quindi ogni esempio qui usa la Responses API.

Quanto costa Grok 4.7?

Sotto i 200.000 token di prompt, Grok 4.7 costa 2 $ per milione di token in input, 0,50 $ per milione di token in input memorizzati in cache e 6 $ per milione di token in output. Una volta che un prompt raggiunge 200.000 token, ogni token in quella richiesta viene fatturato a 4 $, 1 $ e 12 $.

Gli strumenti lato server hanno tariffe separate: la pagina dei prezzi addebita 5 $ per 1.000 chiamate di ricerca web o esecuzione di codice. Le ricerche di documenti allegati costano un centesimo ciascuna e i documenti archiviati hanno anche un addebito giornaliero per GiB. Usa un prompt_cache_key stabile per richieste correlate, ma prevedi budget per input non in cache.

Leggi il costo fatturato da usage.cost_in_usd_ticks. I documenti sul tracciamento dei costi dicono che include caching e addebiti degli strumenti. Dividi il valore per 10^10 per ottenere i dollari.

Perché testare Grok 4.7 sul design di un circuito?

Il progetto di un circuito mette alla prova lettura di documenti, calcoli, uso di strumenti e verifica in un’unica attività. SpaceXAI riporta il 64,0% per Grok 4.7 su EEBench. La metodologia EEBench usa simulazioni e controlli della BOM (bill of materials) invece di un giudice LLM, e EnviroNode segue la stessa regola.

Cosa costruiremo: la revisione del circuito EnviroNode Rev A

EnviroNode Rev A è un nodo sensore alimentato via USB. Puoi scaricare il progetto completo da GitHub.

Lo schema riporta ogni valore di componente di cui Grok ha bisogno per la revisione. Ogni requisito ha un ID come PWR-002 o BW-001, in modo che ogni rilievo possa risalire a una regola.

Schema EnviroNode Rev A con valori. Immagine dell’autore.

Prima che Grok revisioni la scheda, esponi ogni regola che il verificatore userà. La funzione restituisce cinque controlli pass-or-fail costruiti da questi otto requisiti:

• PWR-001: L’ingresso USB rimane tra 4,75 V e 5,25 V
• PWR-002: Il regolatore copre il carico di picco
• PWR-003: I carichi non MCU usano un budget di 10 mA
• SIG-001: Il fondo scala del sensore è 1,0 V
• ADC-001: L’ingresso ADC rimane a 2.250 mV o meno
• ADC-002: L’ingresso ADC raggiunge almeno 1.500 mV
• BW-001: I segnali fino a 100 Hz perdono meno di 1 dB
• BW-002: Il cutoff del filtro resta a 500 Hz o meno

Il modello riceve lo stesso set di requisiti. Nessun limite del verificatore compare solo dopo che Grok propone una correzione.

Quali sono i tre difetti inseriti?

Tre difetti possono essere verificati con i numeri. Il loro conteggio non è incluso nel prompt.

• Regolatore troppo piccolo (PWR-002): il TI TLV700 è classificato per 200 mA, mentre il datasheet dell’ESP32-C3 indica un picco di trasmissione Wi‑Fi di 335 mA e la checklist degli schemi di Espressif richiede almeno 500 mA.

• ADC fuori scala (ADC-001): un guadagno di 3 porta 3,0 V all’ADC, ma l’intervallo effettivo del datasheet arriva a 2.500 mV e il requisito consente il 90% di tale valore.

• Filtro troppo lento (BW-001): 10 kΩ e 1 µF danno un cutoff di 15,9 Hz, mentre i segnali fino a 100 Hz possono perdere al massimo 1 dB.

Il difetto dell’ADC riguarda l’intervallo di misura, non il danneggiamento del pin. Scelte corrette, come la resistenza del LED e il ritardo di CHIP_EN, rendono misurabili i falsi positivi.

Come funziona il loop di revisione?

La revisione ha bisogno di un confine chiaro: Grok propone le modifiche, mentre Python decide pass o fail. Il diagramma mostra dove entrano documenti e strumenti in quel loop.

Il loop di revisione separa proposta e verifica. Immagine dell’autore.

Definisci il successo prima della prima chiamata API. Conta un difetto solo quando Grok lo collega a un requisito e a prove di supporto. Conta una correzione solo quando verify_design() restituisce all_pass = true.

Come configurare la Grok 4.7 API in Python

Ti serviranno una chiave API xAI con crediti prepagati, Python 3.10 o superiore e l’SDK Python di OpenAI puntato alla base URL di xAI. Crea la chiave nella xAI Console, poi installa i pacchetti usati sotto.

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install openai python-dotenv pydantic httpx streamlit
pip install matplotlib schemdraw pytest  # Optional diagrams and verifier tests

Gli esempi di API usano il primo gruppo di pacchetti; il secondo supporta diagrammi e test del repository. Li ho testati con Python 3.11.9, openai 3.19.2, pydantic 2.13.5, streamlit 1.64.0 e httpx 0.28.1. Salva la chiave come variabile d’ambiente XAI_API_KEY e caricala con python-dotenv invece di inserirla nel codice sorgente; la nostra guida agli ambienti virtuali spiega la configurazione se è nuova per te.

Fai la tua prima chiamata all’API Grok 4.7

Se la tua chiave funziona già con la Responses API, passa allo Step 1. Altrimenti, questa richiesta verifica in un colpo solo chiave, base URL e ID modello.

import os
import httpx
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1",
                timeout=httpx.Timeout(3600.0))

response = client.responses.create(
    model="grok-4.7",
    reasoning={"effort": "low"},
    input="In one sentence, what does a low-dropout regulator do?",
)
print(response.output_text)

Una risposta in una frase significa che la configurazione funziona. Il timeout lungo conta più avanti, perché richieste che usano ragionamento e strumenti possono richiedere diversi minuti.

Step 1: Grok 4.7 può revisionare un circuito da un’immagine?

Sì, Grok 4.7 può revisionare uno schema partendo solo da un’immagine, purché il prompt dica chiaramente che non arriveranno strumenti. Il baseline invia il PNG come data URL base64 insieme al testo dei requisiti.

image = {
    "type": "input_image",
    "image_url": f"data:image/png;base64,{SCHEMATIC_B64}",
    "detail": "high",
}
response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": [
        image,
        {"type": "input_text", "text": REVIEW_PROMPT},
    ]}],
)

Il prompt chiede tre sezioni: confermati, richiedono ulteriori prove e verificati e accettabili. Non menziona un numero di difetti o un componente sospetto.

Cosa ha trovato la revisione solo immagine?

Dì esplicitamente al modello quando non sono disponibili strumenti o datasheet. Altrimenti, potrebbe concludere la risposta dicendo che cercherà una specifica a cui non può accedere.

Come notato nel TL;DR, Grok ha confermato il difetto del filtro con un cutoff di 15,9 Hz e 16,1 dB di perdita a 100 Hz. Ha messo regolatore e ADC sotto “richiedono ulteriori prove” invece di indovinare i loro limiti.

Step 2: come aggiungere i datasheet con la Files API

I documenti allegati trasformano una preoccupazione vaga in un’affermazione supportata dai numeri. Carica ogni documento una volta e referenzialo tramite file_id.

with open(DATASHEET_PATH, "rb") as datasheet:
    uploaded = client.files.create(
        file=datasheet,
        purpose="assistants",
        expires_after={"anchor": "created_at", "seconds": 7 * 24 * 3600},
    )
content = [image, *[{"type": "input_file", "file_id": fid} for fid in file_ids],
           {"type": "input_text", "text": EVIDENCE_PROMPT}]

Poiché questo tutorial imposta expires_after a sette giorni, gli ID in cache sono validi solo entro quella finestra. Senza expires_after, xAI mantiene i file caricati fino a quando non li elimini.

Nelle risposte dell’SDK OpenAI catturate qui, la ricerca negli allegati è apparsa come elementi custom_tool_call denominati pdf_search e pdf_browse, mentre l’uso le conteggiava sotto document_search_calls. È un comportamento osservato, non il contratto generale dei tipi di strumenti, quindi il loop controlla anche il contatore d’uso documentato.

Come cambiano i datasheet la revisione?

I documenti hanno risolto le due questioni aperte dello Step 1 e supportato i rilievi su potenza, ADC e filtro. Il rilievo sul regolatore ha citato la classificazione a 200 mA del TLV700, il picco di trasmissione a 335 mA dell’ESP32-C3 e la raccomandazione di alimentazione da 500 mA.

Per il filtro, Grok ha calcolato quali valori di condensatore soddisferebbero entrambe le regole di banda con R5 invariata: circa 32–81 nF. Ogni esca è finita sotto “verificati e accettabili” con una motivazione.

Step 3: come verificare i calcoli con l’esecuzione di codice di Grok 4.7

Code execution è il sandbox Python lato server di xAI, aggiunto a tools come {"type": "code_interpreter"} quando usi il client OpenAI. Il prompt aggiunge una regola: ogni affermazione con un numero deve essere calcolata prima di essere considerata confermata.

La guida all’esecuzione di codice linkata sopra dice che il sandbox non ha accesso alla rete e non mantiene stato tra le richieste. Per qualche numero da datasheet, va bene.

Quali calcoli dovrebbe verificare Grok?

Chiedi a Grok di controllare in uno script budget di potenza, intervallo dell’ADC e banda del filtro. Se i circuiti non fanno per te, salta l’output sotto; il succo segue.

f=  100.0 Hz  |H|=0.157177  attenuation=16.0722 dB
fc required for <= 1 dB at 100 Hz: fc >= 196.5227 Hz
V_adc_fs = 3.0000 V
90% limit = 2.2500 V
required rating = max(headroom, mcu min) = 500.00 mA

Il cutoff minimo di 196,5 Hz è il numero da cui dipende la correzione del filtro, e il codice lo calcola invece di lasciarlo all’aritmetica del modello. Anche l’angolo di tolleranza con la minima attenuazione perde oltre 15 dB a 100 Hz, quindi il verdetto regge.

Step 4: Grok 4.7 può cercare sul web tramite API?

Sì. La ricerca web verifica se i documenti allegati sono ancora aggiornati, dato che i produttori aggiornano i datasheet dopo il cutoff di addestramento di un modello. Restringila ai domini ufficiali così le prove restano di prima parte.

tools = [
    {"type": "code_interpreter"},
    {"type": "web_search", "filters": {"allowed_domains": ["ti.com", "espressif.com"]}},
]

La guida alla ricerca web linkata sopra consente fino a cinque allowed_domains, inclusi sottodomini come docs.espressif.com. Terrei questo step anche quando i datasheet allegati sono aggiornati, perché può intercettare una revisione pubblicata dopo il tuo upload.

Cosa dimostrano le citazioni?

Grok dovrebbe citare la pagina prodotto TI corrente, la documentazione dell’ESP32-C3, la checklist hardware e ogni eventuale errata. Considera quelle citazioni come prova della fonte, non come garanzia che la conclusione ingegneristica sia corretta.

I filtri di dominio possono comunque restituire una pagina irrilevante. Controlla che ogni citazione supporti esattamente il componente e il limite usati nel calcolo.

Grok cerca nei file, calcola, verifica le fonti. Immagine dell’autore.

Step 5: come aggiungere un verificatore con il function calling di Grok 4.7

verify_design() è una semplice funzione Python che gira sulla tua macchina, ed è l’unico giudice del superamento della revisione. Grok propone i valori di progetto tramite function calling, e la funzione li confronta con limiti fissi.

VERIFY_DESIGN_TOOL = {
    "type": "function",
    "name": "verify_design",
    "description": "Deterministically check an EnviroNode revision against EN-REQ-001...",
    "parameters": {
        "type": "object",
        "properties": {
            "revision": {"type": "string"},
            "regulator_part": {"type": "string"},
            "gain_rf_ohm": {"type": "number"},
            "gain_rg_ohm": {"type": "number"},
            "filter_r_ohm": {"type": "number"},
            "filter_c_nf": {"type": "number"},
        },
        "required": ["revision", "regulator_part", "gain_rf_ohm",
                     "gain_rg_ohm", "filter_r_ohm", "filter_c_nf"],
    },
}

La capacità di potenza deve soddisfare max((335 + 10) mA × 1.25, 500 mA). Per l’ADC, 1.0 V × (1 + Rf/Rg) deve rimanere tra 1.500 e 2.250 mV. I controlli del filtro misurano la perdita a 100 Hz e limitano il cutoff a 500 Hz; ogni controllo restituisce un valore, un limite e pass o fail.

Lo schema dello strumento dice solo a Grok quali valori inviare. La logica centrale pass-or-fail è normale Python:

import math

part = PARTS.get(regulator_part.strip().upper())
required_ma = max((335 + 10) * 1.25, 500)
power_ok = (
    part is not None
    and float(part["rated_iout_ma"]) >= required_ma
    and float(part["vin_max_v"]) >= 5.25
    and float(part["vout_v"]) == 3.3
)

gain = 1 + gain_rf_ohm / gain_rg_ohm
adc_mv = gain * 1000

fc = 1 / (2 * math.pi * filter_r_ohm * filter_c_nf * 1e-9)
loss_db = 10 * math.log10(1 + (100 / fc) ** 2)

checks = {
    "PWR-002": power_ok,
    "ADC-001": adc_mv <= 2250,
    "ADC-002": adc_mv >= 1500,
    "BW-001": loss_db <= 1.0,
    "BW-002": fc <= 500,
}
return {"all_pass": all(checks.values()), "checks": checks}

La funzione completa rifiuta anche valori non validi e restituisce le misure con ogni risultato. Testala con un progetto noto-buono, uno noto-cattivo, un componente sconosciuto e un quasi-centro.

Perché dovrebbe essere il codice, e non il modello, a valutare la correzione?

Tieni le specifiche dei componenti fuori dal controllo del modello. Non lascerei che il modello fornisse la propria corrente nominale. Grok invia un codice parte, e la funzione cerca la specifica nel catalogo dell’applicazione.

Un agente non dovrebbe sia proporre una soluzione sia decidere se è corretta quando il codice può verificarla. Sostituisci verify_design() con una suite di test o un controllo di schema quando il compito cambia. Scrivere il verificatore richiede lavoro extra, ma il suo risultato pass o fail non dipende dall’opinione del modello.

Step 6: come riprogettare e verificare il circuito

Dai a Grok un unico obiettivo: correggere ogni violazione confermata con il minor numero ragionevole di modifiche e non dichiarare completo il progetto finché il controllo definito prima non viene superato. Fornisci prove e strumenti dagli Step 3–5, poi imposta un limite di richieste.

Qui conta l’avviso sul contesto del TL;DR. Risolvilo prima di aggiungere altri turn.

Perché i loop ricchi di file richiedono compattazione del contesto?

Una richiesta continuata include i risultati degli strumenti precedenti, e le ricerche nei documenti possono restituire molto testo. Nel prototipo fallito, la continuazione successiva ha raggiunto 1.116.321 token superando la finestra da 500.000 token di Grok 4.7.

La compattazione del contesto non può salvare una richiesta già oltre il limite. Il loop corretto compatta ogni turno con ricerca documentale andata a buon fine prima di inviare la richiesta successiva.

details = (response.usage.model_extra or {}).get(
    "server_side_tool_usage_details", {}
)
observed_attachment_call = any(
    item.type == "custom_tool_call"
    and item.name in {"pdf_search", "pdf_browse"}
    for item in response.output
)
used_documents = (
    details.get("document_search_calls", 0) > 0
    or observed_attachment_call
)

if used_documents:
    compacted = client.responses.compact(
        model="grok-4.7", input=history + list(response.output) + follow_up)
    history = list(compacted.output)  # pass the compaction item back unchanged
    # Compaction drops tool output, so restate the verifier's verdict ourselves.
    history.append({"role": "user", "content":
                    "verify_design results, exactly as returned: " + json.dumps(results)})
else:
    history = history + list(response.output) + follow_up
response = client.responses.create(model="grok-4.7", input=history, tools=TOOLS,
                                   store=False, prompt_cache_key=cache_key)

Tieni quell’ultimo append. La compattazione elimina output verbosi degli strumenti, quindi ribadire il risultato del verificatore aiuta la risposta successiva a evitare controlli inventati o confusi. Compattare dopo ogni turno ricco di documenti è una cadenza conservativa; un sistema più grande può usare invece una soglia sui token in input.

La Rev B ha superato la verifica?

Sì. Grok ha cambiato un componente in ciascun sottosistema in errore: potenza, guadagno dell’ADC e banda del filtro. Il diagramma mostra i valori esatti della Rev A e della Rev B.

Tre modifiche ai componenti correggono la Rev A. Immagine dell’autore.

I valori rivisti passano poi a verify_design(). Restituisce un risultato per ogni requisito.

Il progetto rivisto supera tutti i controlli di verifica. Immagine dell’autore.

Un risultato negativo torna come function_call_output, così Grok può rivedere il progetto finché i controlli non passano o si raggiunge il limite di richieste.

Step 7: come restituire una revisione del circuito strutturata

Gli output strutturati restituiscono un oggetto conforme a uno schema invece di una prosa da dover fare il parse. Chiama client.responses.parse() con un modello Pydantic nella stessa conversazione, con le chiamate agli strumenti disattivate.

class Finding(BaseModel):
    violated_requirement: str
    severity: Literal["blocker", "major", "minor"]
    evidence: list[str]
    recommended_change: str
    verifier_result: Literal["pass", "fail", "not_verified"]

parsed = client.responses.parse(
    model="grok-4.7", input=history + [REPORT_REQUEST],
    text_format=DesignReview, tools=TOOLS, tool_choice="none", store=False,
)

Uno schema valido non prova che il contenuto sia corretto, quindi includi i risultati del verificatore e dì a Grok di basare verifier_result su quelli. Il JSON può poi alimentare un issue tracker o una coda di approvazione umana.

Cosa ha riportato la revisione strutturata?

Il report strutturato dovrebbe segnare ciascun difetto originale come risolto, citare il valore misurato restituito dal verificatore e mantenere le preoccupazioni non testate sotto open_risks. Per questo progetto, tali preoccupazioni includono un regolatore che si trova esattamente sulla soglia di 500 mA e un condensatore ADC diverso dalla raccomandazione di Espressif.

Un maggiore sforzo di ragionamento di Grok 4.7 migliora la revisione del circuito?

Un maggiore sforzo non ha migliorato il punteggio del verificatore, ma ha cambiato la qualità della correzione del filtro. Ogni livello ha ricevuto lo stesso schema, prompt, strumenti e limite di richieste.

low ha ridutto la resistenza e mantenuto il condensatore da 1 µF, lasciando fuori dal verificatore il carico capacitivo e l’assestamento. Le linee guida sul carico capacitivo di Microchip dicono che una resistenza in serie può migliorare la stabilità, quindi questo risultato non prova che la correzione sia instabile; richiede test di risposta in frequenza, risposta al gradino o su banco. high ha cambiato invece il condensatore, mentre xhigh ha scelto gli stessi valori finali di high dopo una chiamata al verificatore in più.

Quando vale la pena lo sforzo di ragionamento xhigh?

Per questo singolo confronto, high ha dato l’equilibrio migliore. Ha evitato la preoccupazione sul carico non modellato senza la chiamata extra al verificatore fatta da xhigh. Un’esecuzione per livello non può stabilire una classifica generale.

Grok 4.7 ha corretto il circuito?

La risposta alla domanda iniziale è sì, entro i cinque controlli del verificatore. La tabella condensa in un’unica vista i rilievi precedenti.

• Immagine e requisiti
  • Aggiunge: Ispezione visiva
  • Esito: Conferma ciò che lo schema da solo può provare
• Datasheet
  • Aggiunge: Limiti del produttore
  • Esito: Converte due questioni aperte in rilievi
• Esecuzione di codice
  • Aggiunge: Calcoli verificati
  • Esito: Misura i problemi di potenza e filtro
• Ricerca web
  • Aggiunge: Fonti ufficiali aggiornate
  • Esito: Verifica se le prove allegate sono aggiornate
• Verificatore locale
  • Aggiunge: Pass o fail da Python
  • Esito: Accetta solo una revisione che supera ogni regola

Grok ha corretto i requisiti codificati. Non ha dimostrato che la scheda rivista fosse elettricamente completa o pronta per la produzione.

I documenti decidono se una preoccupazione ha prove. Python decide se una revisione supera i controlli. Una prosa scorrevole non può sostituire nessuno dei due.

Guarda la revisione in Streamlit

La nostra guida a Streamlit spiega l’interfaccia usata qui. Usa lo streaming per mostrare le chiamate agli strumenti man mano che arrivano, poi mostra i controlli del verificatore e il report finale.