Tutorial API Kimi K3.1 Pro: Bangun Agen CAD 3D dengan Pemeriksaan Mandiri di Python

Gunakan API Kimi K3.1 Pro untuk Membangun Agen Image-to-CAD

Agen image-to-CAD mengubah gambar suatu komponen menjadi model CAD yang dapat Anda edit.

Mengapa Kimi K3.1 Pro dan CadQuery cocok untuk image-to-CAD

Kimi K3.1 Pro dapat membaca empat gambar lalu bereaksi terhadap apa yang dihasilkan oleh kodenya sendiri. Blog Moonshot yang sama yang saya sebutkan sebelumnya melaporkan 92,7% dengan alat dan 72.8% tanpa alat pada tugas Vision2Code BenchCAD, yang menilai kode CAD yang ditulis dari tampilan render suatu komponen. Angka-angka tersebut berasal dari subset 1.000 kasus pada upaya max, dan skor dengan alat menggunakan harness Claude Code, jadi sebagian skornya mungkin berasal dari harness tersebut.

Tolok ukurnya juga mengirimkan keempat tampilan dalam satu gambar dan menskalakan setiap komponen ke ukuran yang sama sebelum penilaian. Uji saya mengirim empat tampilan terpisah plus satu dimensi nyata pada upaya high, jadi anggap angka Moonshot sebagai alasan untuk menjalankan uji, bukan sebagai hasilnya. Saat saya menjalankan percobaan ini, bobot terbuka belum dapat diunduh.

CadQuery dipilih sebagai format keluaran karena sebuah skrip CadQuery sendiri adalah model parametrik. Sebuah lubang adalah pemanggilan fungsi dengan diameter dan posisi, sehingga suntingan berikutnya cukup mengubah satu angka dan padatan dibangun ulang. File STL hanya memberi Anda segitiga, dan tidak ada slot_width untuk diubah.

Apa yang dilihat agen dan apa yang tetap tersembunyi

Kimi menerima empat gambar referensi, lebar 60 mm, dan sebuah prompt sistem. Prompt tersebut menetapkan satuan milimeter dan sumbu, memusatkan komponen pada X dan Y dengan alas di Z=0, serta meminta dimensi bernama dan padatan final pada result.

Setelah itu, Kimi hanya tahu apa yang dilaporkan oleh alatnya. API Kimi tidak menjalankan CadQuery, jadi keempat alat hidup di aplikasi:

• execute_cad menjalankan program dalam kontainer Docker tanpa jaringan dan menyimpan hasilnya sebagai kandidat

• inspect_cad melaporkan validitas, jumlah padatan, bounding box, volume, dan bidang silindris

• render_cad menggambar kandidat dari empat kamera yang sama seperti referensi

• submit_cad mengakhiri satu fase dengan satu kandidat

Kimi tidak pernah melihat kode referensi atau skor apa pun. Evaluator hanya membaca file STEP yang tersimpan setelah agen selesai, jadi skor tidak dapat mengarahkan atau menghentikan agen.

Skor tidak pernah mengalir kembali ke Kimi. Gambar oleh Penulis.

Siapkan API Kimi K3.1 Pro di Python

Untuk menggunakan API Kimi K3.1 Pro di Python, Anda membutuhkan empat hal. Saya menguji semuanya di Linux x86_64 dengan versi berikut:

• Kunci API Kimi dengan pengisian setidaknya $1, sesuai panduan cepat K3.1 Pro

• Python 3.12.3 dengan openai 3.39.0, SDK OpenAI

• cadquery 2.8.0 untuk membangun dan memeriksa padatan

• Docker 29.9.2 untuk sandbox

Cuplikan di bawah ini adalah potongan dari proyek lengkap di repositori GitHub ini, yang akan Anda klon berikutnya.

Instal CadQuery dan bangun sandbox Docker

Panduan instalasi CadQuery menyarankan conda, meskipun pip pada Python 3.12 juga berfungsi. Klon repositori dan lakukan penyiapan:

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/Didukung oleh

Citra sandbox menginstal versi CadQuery yang sama dan berjalan sebagai pengguna reguler. Docker tidak menetapkan batas CPU atau memori secara default, sesuai dokumen batas sumber daya, jadi runner yang menetapkannya. Halaman depan repositori mencantumkan perintah untuk menjalankan dan menilai eksperimen, termasuk jalur tanpa kunci API atau Docker.

Sebelum kode Kimi mencapai kontainer, coba rusakkan sendiri. Program uji saya mencoba membaca kunci API, mengakses jaringan, dan menulis di luar folder sementara, dan ketiganya gagal.

Tiga operasi diblokir di sandbox. Gambar oleh Penulis.

Lakukan panggilan API Kimi K3.1 Pro pertama Anda

Ini adalah SDK OpenAI biasa yang diarahkan ke endpoint Moonshot. Setel reasoning_effort pada setiap permintaan, karena jika dibiarkan kosong akan memberi max, dan Anda tidak bisa mematikan proses berpikir.

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))Didukung oleh

Abaikan temperature, top_p, n, dan kedua penalti, yang dalam panduan cepat tercantum sebagai tetap. Bahkan jawaban satu kalimat seperti ini menghabiskan sebagian besar completion tokens untuk penalaran, jadi atur batas dengan mempertimbangkan hal itu.

Satu permintaan mengonfirmasi kunci dan model. Gambar oleh Penulis.

Jika API Kimi baru bagi Anda, tutorial Kimi K3 saya sebelumnya membahas streaming, pemanggilan alat, caching, dan input visi.

Buat Model CAD Referensi dan Empat Tampilan Uji

Model CAD referensi adalah kunci jawaban Anda, sehingga setiap skor memiliki pembanding yang tepat. Saya menguncinya sebelum permintaan pertama—dari kamera hingga aturan penilaian—dan tidak mengubah apa pun setelah melihat hasil.

Tentukan dimensi braket

Braket berbentuk L, dengan bagian tegak bergabung di belakang alas. Titik origin berada di tengah permukaan bawah, dengan X melintang lebar, bagian depan ke arah −Y, dan Z ke atas:

Saya menempatkan deretan lubang dan slot di tengah permukaan masing-masing dan menggunakan lubang 6,5 mm, ukuran kelonggaran M6 yang umum, karena braket nyata akan demikian. Pilihan itu ternyata menjadi titik lemah braket ini, dan nanti kita bahas alasannya.

Di dalam fungsi build, w, dep, h, dan t menyimpan lebar, kedalaman, tinggi, dan tebal. Ia menyatukan dua pelat dan memotong fiturnya:

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)Didukung oleh

Skrip memeriksa satu padatan valid dengan ukuran yang diharapkan sebelum mengekspor file STEP.

Render empat tampilan dengan kamera tetap

Sebuah renderer NumPy kecil menggambar tampilan depan, atas, kanan, dan isometrik dengan pembingkaian tetap yang sama untuk referensi dan setiap kandidat. Pada 512 px, satu piksel mencakup sekitar 0,19 mm, meskipun pembacaan dari gambar bisa meleset lebih dari itu. Pembingkaian tetap juga membuat kandidat yang terlalu besar atau salah posisi tampak keliru alih-alih di-center ulang.

Keempat gambar yang dikirim ke Kimi. Gambar oleh Penulis.

Tetapkan aturan evaluasi sebelum menjalankan agen

Evaluator mengukur padatan yang diekspor, jadi nama parameter tidak dapat menipunya. Ia memotong setiap file STEP untuk menemukan lubang, slot, dan kedua tebal pelat, serta menghitung voxel IoU—porsi volume yang sama antara dua padatan—pada grid 0,5 mm pada ukuran nyata. Toleransi mengikuti skala piksel: ±0,5 mm untuk ketebalan, diameter lubang, dan lebar slot, serta ±1 hingga ±1,5 mm untuk panjang dan posisi yang dibaca dari gambar.

IoU saja tidak cukup. Menurut saya itu angka yang tumpul, dan saya terus menggunakannya karena tidak ada yang lebih sederhana untuk membandingkan dua padatan. Sebuah L polos tanpa lubang dan tanpa slot masih mendapat skor di atas 0,96, dan komponen yang benar tetapi dibesarkan 20% mendapat skor sempurna 1,0 setelah keduanya diskalakan ke ukuran yang sama.

Itulah mengapa setiap skor di sini dilengkapi dengan 13 pemeriksaan lulus atau gagal. Bahkan 1,0 sempurna hanya berarti dua padatan cocok pada grid tersebut, bukan hingga setiap mikron, dan tidak satu pun dari angka-angka ini merupakan jaminan manufaktur.

Hasilkan Kode CadQuery dari Gambar dengan Kimi K3.1 Pro

Kandidat pertama berasal dari satu permintaan tanpa alat, dan dijalankan persis seperti yang diterima.

Kirim empat tampilan referensi ke API Kimi K3.1 Pro

Input visi Kimi menerima data URL base64 di dalam array content, dan tidak menerima URL gambar publik. Prompt sistem memuat aturan pembingkaian dan penamaan yang saya jelaskan sebelumnya, dan pesan pengguna membawa keempat PNG serta prompt berikut:

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.Didukung oleh

Permintaannya sendiri singkat:

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,
)Didukung oleh

Untuk memeriksa ukuran input sebelum membayar, kirim pesan yang sama ke endpoint estimasi token, yang estimasinya hampir sama persis dengan tagihannya. Empat gambar 512 px kurang dari 2.000 token input.

Jalankan program CadQuery pertama di sandbox

Runner menulis kode ke folder sementara dan memulai kontainer sekali pakai dengan perintah 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)Didukung oleh

Pada percobaan pertama, balasan Kimi memakan waktu sekitar satu menit. Programnya menamai setiap dimensi dalam referensi tersembunyi, dari bracket_depth = 40.0 hingga slot_center_z = 25.5. Ia menghasilkan padatan valid dan lulus semua pemeriksaan.

Kamera sama, skala sama, komponen cocok. Gambar oleh Penulis.

Percobaan pertama yang sempurna membuat saya memeriksa kemungkinan kebocoran, tetapi PNG tidak membawa metadata, dan tidak ada prompt yang memuat nilai tersembunyi. Kode Kimi menjelaskan hasilnya. Seperti yang saya sebutkan saat mendefinisikan braket, fitur-fitur berada di tempat yang akan dipilih desainer, dan Kimi juga begitu.

Kimi menurunkan posisi fitur dari titik tengah. Gambar oleh Penulis.

Bangun Agen Pemanggil Alat dengan Pemeriksaan Mandiri Menggunakan Kimi K3.1 Pro

Agen pemanggilan alat berjalan dalam sebuah loop. Kimi meminta sebuah alat, kode Anda menjalankannya, dan hasilnya dikirim kembali sebagai pesan alat hingga Kimi selesai.

Tiga fase, masing-masing dengan batas tegas. Gambar oleh Penulis.

Definisikan alat untuk mengeksekusi, memeriksa, dan merender CAD

Berikut skema execute_cad. Ia mengembalikan hasil singkat dalam format tetap, dengan beberapa baris terakhir traceback saat program gagal:

{"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"]}}}Didukung oleh

render_cad mengembalikan keempat gambarnya di dalam pesan alat itu sendiri, pola lihat-lagi yang sama seperti pada tutorial visi agens kami dengan Gemini. Dokumen Kimi tidak menunjukkan contohnya, jadi perlakukan ini sebagai perilaku teramati. Di ketiga percobaan, sebuah role: "tool" membawa bagian image_url, dan model membacanya.

Pertahankan pesan asisten penuh dalam loop alat

Ada tiga detail penting di sini, dan dua yang pertama berasal dari panduan model berpikir Kimi di sini dan panduan cepat:

• Kirim pesan asisten lengkap pada setiap giliran, termasuk reasoning_content dan tool_calls

• Tambahkan satu pesan alat per panggilan alat, dengan tool_call_id yang cocok

• Serialisasikan pesan dengan model_dump(), karena SDK OpenAI tidak memiliki field reasoning_content yang bertipe

Loop di bawah ini mengikuti ketiganya:

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})Didukung oleh

Jangan mengandalkan API untuk menangkap kesalahan di sini. Permintaan dengan reasoning_content dihapus dari riwayat tetap berhasil, meski dokumen mewajibkan field tersebut dan menghapusnya dapat mengubah kelanjutan giliran berikutnya. Saya lebih memilih 400 daripada bug yang gagal diam-diam.

Anggaran berada di kode loop, di luar jangkauan Kimi. Setelah 3 perbaikan terpakai, execute_cad menjawab dengan error, dan submit_cad menolak apa pun yang bukan satu padatan valid.

Apa yang terjadi pada fase perbaikan

Tidak banyak, dan saya hampir menghapus bagian ini karena alasan itu. Saya membangun loop perbaikan dengan harapan sebagian besar pekerjaan terjadi di sini, tetapi Kimi hampir tidak menyentuhnya. Ia memeriksa kandidat pertamanya, merendernya, menulis ringkasan yakin bahwa ia cocok dengan keempat tampilan referensi, lalu mengirimkan program yang sama seperti awal.

Ringkasan itu tidak selalu benar. Pada salah satu percobaan, inspect_cad melaporkan jari-jari lubang 3,0 mm, jadi lubang 6,0 mm ketika referensi memiliki 6,5 mm, dan Kimi tetap mengirimkan. Setengah milimeter kurang dari 3 piksel di tampilan ini (saya sendiri pun tidak akan percaya mata pada ukuran itu), dan tidak ada umpan balik yang menyebutkan diameter yang benar.

Alat melaporkan jari-jari 3,0 mm. Gambar oleh Penulis.

Edit Model CAD Parametrik dengan Kimi K3.1 Pro

Dengan loop perbaikan menganggur, perubahan desain menjadi uji yang lebih bermakna. Ini uji yang ringan, meskipun, dan perubahan yang memindahkan dua fitur sekaligus akan mendorong lebih keras.

Minta Kimi melebarkan slot

Pengeditan melanjutkan percakapan yang sama dan dimulai dari kandidat yang diajukan Kimi, bukan dari kode referensi saya:

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.Didukung oleh

Kimi menggunakan salah satu dari 3 program yang diizinkan. Perbedaannya satu baris, dari slot_width = 6.0 menjadi slot_width = 9.0, lalu satu giliran untuk inspeksi dan render, kemudian submit.

Periksa edit pada geometri yang diekspor

Angka baru di kode tidak membuktikan padatan berubah. Evaluator membandingkan padatan sebelum dan sesudah edit voxel demi voxel, mengabaikan hanya ruang yang boleh diambil oleh slot yang lebih lebar:

• Slot selebar 9 mm, dengan panjang dan pusat yang sama
• Lubang, tebal pelat, dan ukuran luar tidak berubah
• Tidak ada material yang berubah di luar area slot

Semua pemeriksaan edit lulus, setiap saat.

Edit berhasil bersih karena slot2D() memperlakukan panjangnya sebagai ujung ke ujung, jadi slot tetap 20 mm dan bagian lurusnya menjadi lebih pendek. Program yang menyimpan jarak antar pusat busur akan membuat slot bertambah 3 mm.

Edit hanya mengubah slot. Gambar oleh Penulis.

Seberapa Akurat Agen CAD Kimi K3.1 Pro?

Agen melewati semua pemeriksaan tersembunyi di ketiga percobaan, dalam batas toleransi yang saya tetapkan sebelumnya. Baca tabel ini sebagai rangkuman:

Tiga percobaan bukan tingkat keberhasilan, hanya tanda bahwa hasil bertahan pada satu braket. Lubang 6,0 mm dari fase perbaikan lolos hanya karena tepat pada toleransi lubang ±0,5 mm, jadi batas yang lebih ketat akan menggagalkan percobaan itu.

Koreksi mandiri tidak memiliki apa pun untuk diperbaiki

Uji yang akan menunjukkan apakah loop meningkatkan model adalah run injeksi kesalahan, yang memulai agen dari program dengan kesalahan yang diketahui. Saya akan melaporkannya terpisah dari percobaan ini.

Biaya token dan waktu per percobaan

Setiap percobaan menelan biaya 6,3 hingga 7,3 sen untuk enam permintaan dan tujuh panggilan alat. Itu hanya biaya API, karena rendering dan Docker berjalan di mesin saya.

Hitung harga setiap permintaan dari field usage pada tarif yang dipublikasikan untuk kimi-k3.1-pro. Per sejuta token: $2,00 untuk input, $10,00 untuk output, $0,20 untuk cache hit, dan $2,00 untuk penulisan cache 5 menit.

Permintaan pertama yang paling mahal karena di situlah Kimi melakukan penalaran. Output lebih dari separuh tagihan dan penulisan cache 23% hingga 35%, sementara cache hit hampir tidak berbiaya. Berikut bagaimana tiga field input dijumlahkan, sesuai referensi Chat Completions yang saya tautkan sebelumnya, dan Anda bisa melewatinya jika pelacak Anda sudah memisahkan penulisan 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) / 1e6Didukung oleh

Token penalaran sudah termasuk dalam completion_tokens, jadi jangan menambahkannya dua kali. Penulisan cache 5 menit biayanya sama dengan input tanpa cache, jadi prompt caching menghemat hanya saat sebuah prefix dibaca kembali. Loop alat mengirim ulang riwayat yang sama setiap giliran, dan di sini caching memangkas tagihan input menjadi kurang dari 40% dari tarif biasa.

Satu percobaan memakan waktu sekitar tiga menit, sebagian besar untuk menunggu, karena klien memberi jarak 21 detik antar permintaan untuk batas laju yang akan saya bahas di FAQ.

Keterbatasan Generasi CAD AI dari Gambar

Batas utama adalah gambar tidak dapat memuat semua dimensi. Uji saya menambah beberapa lagi:

• Render tidak dapat menampilkan detail yang lebih kecil dari satu piksel. Jika sebuah dimensi penting, berikan sebagai teks atau ukur dengan alat.
• Braket ini mudah ditebak. Lubang tidak terpusat dan ukuran ganjil akan menguji apakah Kimi membaca piksel atau kebiasaan desain.
• Flag Docker hanya memblokir apa yang mereka sebutkan. Mereka menghentikan program nakal dari bagian penyiapan, tetapi kode model masih dapat menghabiskan satu menit penuh CPU. Panduan kami tentang mengamankan agen AI di kontainer membahas lapisan berikutnya.
• Lulus pemeriksaan ini tidak mengatakan apa pun tentang kekuatan. Beban, material, sudut dalam membulat yang dibutuhkan komponen nyata, kecocokan baut, dan bagaimana toleransi saling menumpuk berada di luar uji ini.

Braket yang mudah lebih merupakan batas uji saya daripada batas Kimi.

Penutup

Kita membangun agen yang menulis kode CadQuery parametrik dari empat gambar, memeriksa padatannya sendiri dengan alat, dan mengedit satu fitur sesuai permintaan. Untuk braket ini, jawaban atas pertanyaan pembuka saya adalah ya. Ketiga percobaan lulus pada permintaan pertama dalam batas toleransi yang saya tetapkan, dan edit slot tidak mengganggu bagian lain.

Loop perbaikan adalah bagian yang tidak bisa saya jaminkan, karena Kimi tidak pernah menemukan apa pun untuk diperbaiki. Tinjauannya membiarkan satu kesalahan 0,5 mm lolos karena ia melihat piksel, bukan diameter sebenarnya. Saya tidak akan menggeneralisasi hasil ini ke komponen berukuran ganjil atau foto komponen nyata.

Yang dapat dibawa adalah metode menyembunyikan referensi, membekukan aturan penilaian sebelum permintaan pertama, dan menilai padatan yang diekspor alih-alih kodenya. Kimi mengatakan kandidatnya cocok tiga kali, dan hanya evaluator yang bisa mengatakan bahwa dua benar dan satu hampir. Evaluator itulah yang akan saya pertahankan, dan run injeksi kesalahan akan menjadi ekstensi pertama saya.

Untuk selengkapnya tentang menghubungkan model ke alat Anda sendiri, kursus Developing AI Systems with the OpenAI API kami membahas function calling dengan SDK yang sama yang digunakan agen ini.