Tutorial API Kimi K3.1 Pro: crea un agente CAD 3D autoverificante in Python

Usa l'API Kimi K3.1 Pro per creare un agente Image-to-CAD

Un agente image-to-CAD trasforma immagini di un pezzo in un modello CAD che puoi modificare.

Perché Kimi K3.1 Pro e CadQuery sono adatti all'image-to-CAD

Kimi K3.1 Pro può leggere quattro immagini e poi reagire a ciò che produce il proprio codice. Lo stesso blog di Moonshot citato prima riporta il 92,7% con strumenti e 72.8% senza su il task Vision2Code di BenchCAD, che valuta il codice CAD scritto da viste renderizzate di un pezzo. Queste cifre provengono da un sottoinsieme di 1.000 casi con sforzo max, e il punteggio con strumenti ha usato l'harness Claude, quindi parte di quel punteggio potrebbe spettare all'harness.

Il benchmark invia anche tutte e quattro le viste in un'unica immagine e ridimensiona ogni pezzo alla stessa dimensione prima di valutare. Il mio invia quattro viste separate più una quota reale con sforzo high, quindi prendi il numero di Moonshot come un motivo per eseguire il test, non come il suo risultato. Quando ho eseguito queste prove, i pesi open non erano ancora scaricabili.

CadQuery è il formato di output perché uno script CadQuery è esso stesso un modello parametrico. Un foro è una chiamata con un diametro e una posizione, quindi una modifica successiva cambia un numero e il solido si ricostruisce. Un file STL ti dà triangoli, e non c'è slot_width da modificare.

Cosa vede l'agente e cosa resta nascosto

Kimi riceve le quattro immagini di riferimento, la larghezza di 60 mm e un prompt di sistema. Quel prompt fissa millimetri e assi, centra il pezzo su X e Y con il fondo a Z=0 e chiede dimensioni con nome e un solido finale in result.

Dopodiché, Kimi sa solo ciò che riportano i suoi strumenti. L'API Kimi non esegue CadQuery, quindi tutti e quattro gli strumenti vivono nell'applicazione:

• execute_cad esegue un programma in un container Docker senza rete e salva il risultato come candidato

• inspect_cad riporta validità, numero di solidi, bounding box, volume e facce cilindriche

• render_cad disegna il candidato dalle stesse quattro camere del riferimento

• submit_cad conclude una fase con un candidato

Kimi non vede mai il codice di riferimento né alcun punteggio. L'evaluator legge solo i file STEP salvati dopo che l'agente ha finito, quindi un punteggio non può guidare o fermare l'agente.

I punteggi non tornano mai a Kimi. Immagine dell'autore.

Configura l'API Kimi K3.1 Pro in Python

Per usare l'API Kimi K3.1 Pro in Python, ti servono quattro cose. Ho testato tutto su Linux x86_64 con queste versioni:

• Una chiave API Kimi con almeno $1 di ricarica, come nel quickstart di K3.1 Pro

• Python 3.12.3 con openai 3.39.0, l'SDK OpenAI

• cadquery 2.8.0 per costruire e controllare solidi

• Docker 29.9.2 per la sandbox

Gli snippet sotto sono estratti dal progetto completo in questo repository GitHub, che clonerai tra poco.

Installa CadQuery e crea la sandbox Docker

La guida all'installazione di CadQuery preferisce conda, anche se pip su Python 3.12 funziona. Clona il repository e configuralo:

git clone https://github.com/KhalidAbdelaty/Kimi_K3.1_Pro_API_Tutorial.git
cd Kimi_K3.1_Pro_API_Tutorial
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env             # then add your MOONSHOT_API_KEY
docker build -t cad-sandbox:2.8.0 sandbox/Offerto da

L'immagine della sandbox installa la stessa versione di CadQuery ed è eseguita come utente normale. Docker non imposta limiti di CPU o memoria per impostazione predefinita, come riportato nella sua documentazione sui vincoli di risorse, quindi il runner li imposta. La pagina iniziale del repository elenca i comandi per eseguire e valutare l'esperimento, incluso un percorso senza chiave API né Docker.

Prima che il codice di Kimi arrivi al container, prova a romperlo tu. Il mio programma di test ha provato a leggere la chiave API, raggiungere la rete e scrivere fuori dalla sua cartella temporanea, e tutti e tre i tentativi sono falliti.

Tre operazioni bloccate nella sandbox. Immagine dell'autore.

Esegui la tua prima chiamata all'API Kimi K3.1 Pro

Questa è la normale SDK OpenAI puntata sull'endpoint di Moonshot. Imposta reasoning_effort su ogni richiesta, perché lasciarlo vuoto dà max, e non puoi disattivare il ragionamento.

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1")

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    reasoning_effort="high",        # low, high, or max; the API default is max
    max_completion_tokens=2048,     # reasoning and answer share this cap
    messages=[{"role": "user", "content": "In one sentence, what does a STEP file store?"}],
)
print(response.choices[0].message.content)
print("usage:", response.usage.model_dump(exclude_none=True))Offerto da

Lascia fuori temperature, top_p, n e entrambe le penalità, che il quickstart indica come fissi. Anche una risposta di una frase come questa spende la maggior parte dei suoi token di completamento nel ragionamento, quindi dimensiona il limite tenendone conto.

Una richiesta conferma chiave e modello. Immagine dell'autore.

Se l'API Kimi è nuova per te, il mio tutorial su Kimi K3 precedente copre streaming, chiamata di strumenti, caching e input visivo.

Crea un modello CAD di riferimento e quattro viste di test

Un modello CAD di riferimento è la tua chiave di correzione, così ogni punteggio ha qualcosa di esatto con cui confrontarsi. Io ho bloccato il mio prima della prima richiesta, dalle camere alle regole di valutazione, e non ho cambiato nulla dopo aver visto i risultati.

Definisci le dimensioni della staffa

La staffa è una L, con il montante unito sul retro della base. Il suo origine si trova al centro della faccia inferiore, con X lungo la larghezza, il fronte verso −Y e Z verso l'alto:

Ho messo la fila di fori e l'asola al centro delle rispettive facce e ho usato fori da 6,5 mm, una comune misura di passaggio per M6, perché una staffa reale lo farebbe. Quella scelta si è rivelata il punto debole di questa staffa, e vedremo perché.

Dentro la funzione di build, w, dep, h e t contengono larghezza, profondità, altezza e spessore. Unisce le due piastre e ricava le caratteristiche:

base = cq.Workplane("XY").box(w, dep, t, centered=(True, True, False))
upright = cq.Workplane("XY").center(0, dep / 2 - t / 2).box(w, t, h, centered=(True, True, False))
holes = cq.Workplane("XY").pushPoints([(-17, -3), (17, -3)]).circle(3.25).extrude(t)
slot = (cq.Workplane("XZ", origin=(0, dep / 2 - t / 2, 0)).center(0, 25.5)
        .slot2D(20, 6, 90)            # end-to-end length, width, angle
        .extrude(t, both=True))
result = base.union(upright).cut(holes).cut(slot)Offerto da

Lo script controlla che ci sia un unico solido valido della dimensione attesa prima di esportare un file STEP.

Renderizza quattro viste con camere fisse

Un piccolo renderer NumPy disegna viste frontale, superiore, destra e isometrica con lo stesso inquadramento fisso per il riferimento e per ogni candidato. A 512 px, un pixel copre circa 0,19 mm, anche se una lettura dall'immagine può sforare di più. L'inquadramento fisso fa anche sì che un candidato troppo grande o fuori posto appaia sbagliato invece di essere ri-centrato.

Le quattro immagini inviate a Kimi. Immagine dell'autore.

Imposta le regole di valutazione prima di eseguire l'agente

Il valutatore misura il solido esportato, quindi i nomi dei parametri non possono ingannarlo. Seziona ogni file STEP per trovare i fori, l'asola e gli spessori delle due piastre, e calcola la voxel IoU, la quota di volume che due solidi hanno in comune, su una griglia da 0,5 mm a grandezza reale. Le tolleranze seguono la scala dei pixel: ±0,5 mm per spessori, diametri dei fori e larghezza dell'asola, e ±1 a ±1,5 mm per lunghezze e posizioni lette dalle immagini.

La sola IoU non basta. La trovo un numero grossolano, e continuo a usarla perché nulla di più semplice confronta due solidi. Una L semplice senza fori né asola supera comunque 0,96, e il pezzo giusto ingrandito del 20% ottiene un perfetto 1,0 una volta che entrambi sono scalati alla stessa dimensione.

Per questo ogni punteggio qui arriva con 13 controlli superati o falliti. Anche un 1,0 perfetto significa solo che due solidi coincidono su quella griglia, non al micron, e nessuno di questi numeri è una garanzia di produzione.

Genera codice CadQuery dalle immagini con Kimi K3.1 Pro

Il primo candidato arriva da una richiesta senza strumenti, ed è eseguito esattamente così come restituito.

Invia quattro viste di riferimento all'API Kimi K3.1 Pro

L'input visivo di Kimi accetta data URL base64 dentro un array content, e non accetta URL pubblici di immagini. Il prompt di sistema contiene l'inquadramento e le regole di denominazione descritte prima, e il messaggio utente porta i quattro PNG e questo prompt:

These four images show one mechanical part, a bracket. Each view uses orthographic
projection, and all four use the same scale. The camera for each view is written at the
top of the image, and a small axis triad sits in the lower-left corner.

The overall width of the part along X is 60 mm. No other dimension is given, so estimate
the rest from the images.

Write one CadQuery program that rebuilds this part as an editable parametric model.
Return the complete program in a single python code block.Offerto da

La richiesta in sé è breve:

images = [image_part(path) for path in view_paths]   # four PNGs as base64 data URLs
messages.append({"role": "user", "content": images + [{"type": "text", "text": BASELINE_PROMPT}]})
response = client.chat.completions.create(
    model="kimi-k3.1-pro", reasoning_effort="high",
    max_completion_tokens=32_768, messages=messages,
)Offerto da

Per controllare la dimensione dell'input prima di pagare, invia gli stessi messaggi all'endpoint di stima dei token, la cui stima ha quasi coinciso con il conto. Quattro immagini da 512 px sono meno di 2.000 token di input.

Esegui il primo programma CadQuery in una sandbox

Il runner scrive il codice in una cartella temporanea e avvia un container usa e getta con il comando docker run:

cmd = ["docker", "run", "--rm", "--network", "none", "--read-only",
       "--tmpfs", "/tmp:size=64m", "--cap-drop", "ALL",
       "--security-opt", "no-new-privileges",
       "--memory", "1g", "--cpus", "1", "--pids-limit", "128",
       "-v", f"{work}:/work", "cad-sandbox:2.8.0"]
subprocess.run(cmd, capture_output=True, text=True, timeout=60)Offerto da

Nella prima prova, la risposta di Kimi ha impiegato circa un minuto. Il suo programma ha dato un nome a ogni dimensione nel riferimento nascosto, da bracket_depth = 40.0 a slot_center_z = 25.5. Ha prodotto un solido valido e superato ogni controllo.

Stessa camera, stessa scala, pezzi corrispondenti. Immagine dell'autore.

Un primo tentativo perfetto mi ha fatto controllare eventuali fughe, ma i PNG non contengono metadati e nessun prompt include valori nascosti. Il codice di Kimi spiega il risultato. Come ho detto definendo la staffa, le caratteristiche stanno dove le metterebbe un progettista, e così ha fatto Kimi.

Kimi ricava le posizioni dalle mezzerie. Immagine dell'autore.

Costruisci un agente a chiamata di strumenti con autocontrollo con Kimi K3.1 Pro

Un agente a chiamata di strumenti gira in loop. Kimi chiede uno strumento, il tuo codice lo esegue e il risultato torna come messaggio di tool finché Kimi ha finito.

Tre fasi, ciascuna con limiti rigidi. Immagine dell'autore.

Definisci strumenti per eseguire, ispezionare e renderizzare il CAD

Ecco execute_cad come schema. Restituisce un breve risultato in formato fisso, con le ultime righe dello stack trace quando un programma fallisce:

{"type": "function", "function": {
    "name": "execute_cad",
    "description": "Run a complete CadQuery program in an isolated sandbox. Returns a "
                   "candidate id, whether it ran, and a short error if it did not.",
    "parameters": {"type": "object", "properties": {
        "code": {"type": "string",
                 "description": "The complete program. It must assign the final solid to result."}},
        "required": ["code"]}}}Offerto da

render_cad restituisce le sue quattro immagini all'interno dello stesso messaggio di tool, lo stesso schema di guarda-di-nuovo che il nostro tutorial sulla visione agentica usa con Gemini. I documenti di Kimi non mostrano un esempio di questo, quindi trattalo come comportamento osservato. In tutte e tre le prove, un messaggio con role: "tool" conteneva parti image_url e il modello le leggeva.

Mantieni il messaggio completo dell'assistente nel loop degli strumenti

Qui contano tre dettagli, e i primi due vengono dalla guida ai modelli di pensiero di Kimi e dal quickstart: thinking models guide

• Invia indietro a ogni turno l'intero messaggio dell'assistente, inclusi reasoning_content e tool_calls

• Aggiungi un messaggio di tool per ogni chiamata di tool, con l'tool_call_id corrispondente

• Serializza il messaggio con model_dump(), perché l'SDK OpenAI non ha un campo tipizzato reasoning_content

Il loop sotto segue tutti e tre:

message = response.choices[0].message.model_dump(exclude_none=True)
messages.append(message)        # all of it, or the next turn quietly loses its reasoning
for call in message.get("tool_calls") or []:
    content = run_tool(call["function"]["name"], json.loads(call["function"]["arguments"]))
    messages.append({"role": "tool", "tool_call_id": call["id"], "content": content})Offerto da

Non fare affidamento sull'API per intercettare un errore qui. Una richiesta con reasoning_content rimosso dalla cronologia va comunque a buon fine, anche se i documenti richiedono il campo e rimuoverlo può cambiare l'andamento dei turni successivi. Preferirei un 400 a un bug che fallisce in silenzio.

Il budget vive nel codice del loop, dove Kimi non può cambiarlo. Una volta esaurite le 3 riparazioni, execute_cad risponde con un errore, e submit_cad rifiuta tutto ciò che non sia un unico solido valido.

Cosa è successo nella fase di riparazione

Poco, e quasi tagliavo questa sezione per quel motivo. Ho costruito il loop di riparazione aspettandomi che facesse gran parte del lavoro, e Kimi lo ha appena sfiorato. Ha ispezionato il suo primo candidato, lo ha renderizzato, ha scritto un riepilogo sicuro di sé dicendo che corrispondeva a tutte e quattro le viste di riferimento, e ha inviato lo stesso programma con cui aveva iniziato.

Quel riepilogo non era sempre corretto. In una prova, inspect_cad ha riportato un raggio foro di 3,0 mm, quindi fori da 6,0 mm dove il riferimento ha 6,5 mm, e Kimi ha comunque inviato. Mezzo millimetro sono meno di 3 pixel in queste viste (non mi fiderei nemmeno dei miei occhi a quella scala), e nulla nel feedback diceva quale fosse il diametro giusto.

Lo strumento ha riportato raggi di 3,0 mm. Immagine dell'autore.

Modifica un modello CAD parametrico con Kimi K3.1 Pro

Con il loop di riparazione inattivo, la modifica di progetto è diventata il test più indicativo. È comunque un test blando, e una modifica che sposta due caratteristiche insieme metterebbe alla prova molto di più.

Chiedi a Kimi di allargare l'asola

La modifica continua la stessa conversazione e parte dal candidato inviato da Kimi, non dal mio codice di riferimento:

Increase the width of the vertical slot in the upright plate from 6 mm to 9 mm. 
Keep the slot's center position and its end-to-end length as they are in your model. 
Do not change the mounting holes, the plate thickness, or the outer dimensions.Offerto da

Kimi ha usato uno dei 3 programmi consentiti. Il diff è una riga, da slot_width = 6.0 a slot_width = 9.0, poi un turno per ispezionare e renderizzare e un invio.

Controlla la modifica sulla geometria esportata

Un numero nuovo nel codice non prova che il solido sia cambiato. Il valutatore ha confrontato i solidi prima e dopo la modifica voxel per voxel, ignorando solo lo spazio che l'asola più larga è autorizzata a occupare:

• L'asola è larga 9 mm, con la stessa lunghezza e lo stesso centro
• Fori, spessore piastra e dimensioni esterne sono invariati
• Nessun materiale è cambiato fuori dall'area dell'asola

Ogni controllo della modifica è passato, ogni volta.

La modifica ha funzionato pulitamente perché slot2D() considera la lunghezza da estremità a estremità, quindi l'asola è rimasta lunga 20 mm e la parte diritta si è accorciata. Un programma che avesse memorizzato la distanza tra i centri dei due archi avrebbe allungato l'asola di 3 mm.

La modifica ha interessato solo l'asola. Immagine dell'autore.

Quanto è stato accurato l'agente CAD Kimi K3.1 Pro?

L'agente ha superato tutti i controlli nascosti in tutte e tre le prove, entro le tolleranze fissate in anticipo. Leggi la tabella come un riepilogo:

Tre prove non fanno una percentuale di successo, solo un segnale che il risultato ha retto su una staffa. I fori da 6,0 mm della fase di riparazione sono passati solo perché erano esattamente sul margine di ±0,5 mm di tolleranza del foro, quindi un limite più severo avrebbe fatto fallire quella prova.

L'autocorrezione non aveva nulla da correggere

Il test che mostrerebbe se il loop migliora un modello è un run con iniezione di errore, che avvia l'agente da un programma con un errore noto. Lo riporterei a parte rispetto a queste prove.

Costo in token e tempo di esecuzione per prova

Ogni prova è costata da 6,3 a 7,3 centesimi per sei richieste e sette chiamate di strumenti. Sono solo addebiti API, dato che rendering e Docker giravano sulla mia macchina.

Prezza ogni richiesta dai campi usage alle tariffe pubblicate per kimi-k3.1-pro. Per milione di token: $2,00 per input, $10,00 per output, $0,20 per cache hit e $2,00 per scritture di cache di 5 minuti.

La prima richiesta costa di più perché è lì che Kimi ragiona. L'output è più della metà del conto e le scritture di cache il 23%-35%, mentre le cache hit costano quasi nulla. Ecco come si sommano i tre campi di input, secondo la reference di Chat Completions linkata prima; puoi saltarlo se il tuo tracker già separa le scritture di cache:

uncached = u.prompt_tokens - cached - written   # the three parts sum to prompt_tokens
cost = (uncached * 2.00 + cached * 0.20 + written * 2.00 + u.completion_tokens * 10.00) / 1e6Offerto da

I token di ragionamento sono già dentro completion_tokens, quindi non aggiungerli una seconda volta. Una scrittura di cache di 5 minuti costa quanto l'input non in cache, quindi il prompt caching conviene solo quando un prefisso viene riletto. I loop di strumenti reinviano la stessa cronologia a ogni turno, e qui la cache ha ridotto il conto dell'input a meno del 40% della tariffa piena.

Una prova richiede circa tre minuti, soprattutto di attesa, perché il client distanzia le richieste di 21 secondi per il rate limit che tratterò nelle FAQ.

Dove l'AI per generare CAD da immagini è carente

Il limite principale è che le immagini non possono portare ogni dimensione. Il mio test ne aggiunge alcuni:

• I render non possono mostrare dettagli più piccoli di un pixel. Se una dimensione conta, fornisci un testo o misurala con uno strumento.
• La staffa era facile da indovinare. Fori decentrati e misure insolite testerebbero se Kimi legge i pixel o le abitudini di progetto.
• I flag di Docker bloccano solo ciò che nominano. Hanno fermato il programma scorretto della sezione di setup, ma il codice del modello può comunque bruciare il suo minuto pieno di CPU. La nostra guida alla messa in sicurezza di agenti AI in container copre i livelli successivi.
• Superare questi controlli non dice nulla sulla resistenza. Carico, materiale, lo spigolo interno raccordato che un pezzo reale richiederebbe, l'accoppiamento delle viti e come si sommano le tolleranze sono fuori da questo test.

La semplicità della staffa è più un limite del mio test che di Kimi.

Considerazioni finali

Abbiamo costruito un agente che scrive codice CadQuery parametrico da quattro immagini, controlla il proprio solido con strumenti e modifica una caratteristica su richiesta. Per questa staffa, la risposta alla mia domanda iniziale è sì. Tutte e tre le prove sono passate alla prima richiesta entro le tolleranze fissate, e la modifica dell'asola ha lasciato il resto del pezzo intatto.

Il loop di riparazione è la parte che non posso garantire, dato che Kimi non ha mai trovato nulla da riparare. La sua revisione ha lasciato passare l'unico errore da 0,5 mm perché ha visto pixel, mai il diametro vero. Non generalizzerei il risultato a un pezzo di dimensioni insolite o a foto di uno reale.

Ciò che resta valido è il metodo di nascondere il riferimento, congelare le regole di valutazione prima della prima richiesta e valutare il solido esportato invece del codice. Kimi ha detto che il suo candidato corrispondeva tre volte, e solo il valutatore ha potuto dire che era giusto due volte e vicino una volta. Quel valutatore è ciò che terrei, e un run con iniezione di errore sarebbe la mia prima estensione.

Per saperne di più sul collegare i modelli ai tuoi strumenti, il nostro corso Developing AI Systems with the OpenAI API copre la function calling con lo stesso SDK usato da questo agente.