Kimi K3.1 Pro API Eğitimi: Python’da Kendini Kontrol Eden 3B CAD Aracısı Oluşturun

Kimi K3.1 Pro API’sini Kullanarak Görüntüden-CAD’e Bir Aracı Oluşturun

Görüntüden-CAD’e bir aracı, bir parçanın resimlerini düzenleyebileceğiniz bir CAD modeline dönüştürür.

Neden Kimi K3.1 Pro ve CadQuery görüntüden-CAD’e uygundur

Kimi K3.1 Pro dört görüntüyü okuyabilir ve sonra kendi kodunun ürettiğine tepki verebilir. Az önce andığım aynı Moonshot blogu, araçlarla %92,7 ve araçsız %72.8’i BenchCAD’in Vision2Code görevinde raporluyor; bu görev, bir parçanın oluşturulmuş görünümlerinden yazılan CAD kodunu puanlıyor. Bu sayılar max çabasında 1.000 vakalık bir alt kümeden geliyor ve araçlı puan, Claude Code harness'i kullandı; dolayısıyla puanın bir kısmı harness’e ait olabilir.

Kıyaslama ayrıca dört görünümü tek bir görüntüde gönderiyor ve puanlamadan önce her parçayı aynı boyuta ölçekliyor. Benim kurulumum dört ayrı görünüm ve bir gerçek boyutu high çabasıyla gönderiyor; bu yüzden Moonshot’ın sayısını, sonucu değil testi çalıştırmak için bir gerekçe olarak alın. Bu denemeleri çalıştırdığımda, açık ağırlıklar henüz indirilebilir değildi.

Çıktı formatı CadQuery çünkü bir CadQuery betiği başlı başına parametrik bir modeldir. Bir delik, çap ve konum alan bir çağrıdır; dolayısıyla sonraki bir düzenleme bir sayıyı değiştirir ve katı yeniden inşa olur. Bir STL dosyası size üçgenler verir ve değiştirecek bir slot_width yoktur.

Ajanın gördükleri ve gizli kalanlar

Kimi, dört referans görüntüyü, 60 mm genişliği ve bir sistem komutunu alır. Bu komut milimetreleri ve eksenleri sabitler, parçayı X ve Y’de ortalar, altını Z=0’a koyar ve result içinde adlandırılmış boyutlar ve nihai bir katı ister.

Bundan sonra Kimi yalnızca araçlarının bildirdiklerini bilir. Kimi API’si CadQuery’yi çalıştırmaz; bu yüzden dört aracın tamamı uygulamanın içinde yer alır:

• execute_cad bir programı ağsız bir Docker konteynerinde çalıştırır ve sonucu aday olarak kaydeder

• inspect_cad geçerlilik, katı sayısı, sınırlayıcı kutu, hacim ve silindirik yüzleri raporlar

• render_cad adayı referansla aynı dört kameradan çizer

• submit_cad bir aşamayı tek bir adayla bitirir

Kimi hiçbir zaman referans kodu ya da herhangi bir puanı görmez. Değerlendirici, ajan bittikten sonra yalnızca kaydedilmiş STEP dosyalarını okur; dolayısıyla bir puan ajanı yönlendiremez veya durduramaz.

Puanlar asla Kimi’ye geri akmaz. Görsel: Yazar.

Python’da Kimi K3.1 Pro API’sini Kurun

Python’da Kimi K3.1 Pro API’sini kullanmak için dört şeye ihtiyacınız var. Her şeyi Linux x86_64 üzerinde şu sürümlerle test ettim:

• K3.1 Pro hızlı başlangıca göre en az 1 $ bakiyesi olan bir Kimi API anahtarı

• OpenAI SDK’sı olan openai 3.39.0 ile Python 3.12.3

• Katıları oluşturup kontrol etmek için cadquery 2.8.0

• Korumalı alan için Docker 29.9.2

Aşağıdaki parçalar, bu GitHub deposundaki tam projenin alıntılarıdır; şimdi onu klonlayacaksınız.

CadQuery’yi kurun ve Docker korumalı alanını oluşturun

CadQuery’nin kurulum kılavuzu conda’yı tercih eder; ancak Python 3.12 üzerinde pip de çalışır. Depoyu klonlayıp kurun:

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/Altyapı:

Korumalı alan imajı aynı CadQuery sürümünü kurar ve normal bir kullanıcı olarak çalışır. Docker, kaynak kısıtları dokümanına göre varsayılan olarak CPU veya bellek sınırı koymaz; bu nedenle çalıştırıcı bunları ayarlar. Depo ön sayfası, API anahtarı veya Docker olmadan bir yol dahil, deneyi çalıştırıp puanlamak için komutları listeler.

Kimi’nin kodu konteynere ulaşmadan önce, onu kendiniz kırmayı deneyin. Test programım API anahtarını okumayı, ağa ulaşmayı ve çizik klasörü dışına yazmayı denedi; üçü de başarısız oldu.

Korumalı alanda engellenen üç işlem. Görsel: Yazar.

İlk Kimi K3.1 Pro API çağrınızı yapın

Bu, Moonshot’ın uç noktasına yönlendirilmiş sıradan OpenAI SDK’sıdır. Her istekte reasoning_effort ayarlayın; çünkü bunu boş bırakırsanız max alırsınız ve düşünmeyi kapatamazsınız.

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))Altyapı:

temperature, top_p, n ve her iki cezayı da eklemeyin; hızlı başlangıçta bunların sabit olduğu yazıyor. Bu gibi tek cümlelik bir yanıt bile tamamlanma jetonlarının çoğunu muhakemeye harcar; bu yüzden üst sınırı buna göre boyutlandırın.

Tek istek anahtar ve modeli doğrular. Görsel: Yazar.

Kimi API’si sizin için yeniyse, önceki Kimi K3 eğitimim akış, araç çağırma, önbellekleme ve görsel girişi kapsar.

Bir Referans CAD Modeli ve Dört Test Görünümü Oluşturun

Bir referans CAD modeli sizin cevap anahtarınızdır; böylece her puanın karşılaştıracağı kesin bir şey olur. Ben, kameralardan puanlama kurallarına kadar her şeyi ilk istekten önce kilitledim ve sonuçları gördükten sonra hiçbirini değiştirmedim.

Braket ölçülerini tanımlayın

Braket bir L’dir; dikey parça tabanın arkasından birleşir. Kökeni, alt yüzün ortasında durur; X genişlik boyunca, ön –Y yönüne, Z yukarıya bakar:

Delik sırasını ve uzun deliği yüzlerinin ortasına koydum ve gerçek bir brakette olacağı gibi yaygın bir M6 boşluk ölçüsü olduğundan 6,5 mm delikler kullandım. Bu tercih bu brakette zayıf noktaya dönüştü; nedenini birazdan göreceğiz.

Oluşturma fonksiyonu içinde w, dep, h ve t genişliği, derinliği, yüksekliği ve kalınlığı tutar. İki plakayı birleştirir ve özellikleri keser:

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)Altyapı:

Betik, bir STEP dosyası dışa aktarmadan önce beklenen boyutta tek bir geçerli katı olup olmadığını kontrol eder.

Sabit kameralarda dört görünüm oluşturun

Küçük bir NumPy çizici, referans ve her aday için aynı sabit kadrajla ön, üst, sağ ve izometrik görünümleri çizer. 512 pikselde bir piksel yaklaşık 0,19 mm’yi kapsar; ancak görüntüden bir okuma bundan daha fazla sapabilir. Sabit kadraj, ayrıca çok büyük ya da yanlış konumlandırılmış bir adayı yeniden ortalamak yerine yanlış görünmesini sağlar.

Kimi’ye gönderilen dört görüntü. Görsel: Yazar.

Ajanı çalıştırmadan önce değerlendirme kurallarını ayarlayın

Değerlendirici dışa aktarılan katıyı ölçer; bu nedenle parametre adları onu kandıramaz. Her STEP dosyasını dilimleyerek delikleri, uzun deliği ve her iki plaka kalınlığını bulur; ayrıca gerçek boyutta 0,5 mm ızgarada, iki katının ortak hacim payı olan voksel IoU’yu hesaplar. Toleranslar piksel ölçeğini izler: kalınlıklar, delik çapları ve uzun delik genişliği için ±0,5 mm; görüntülerden okunan uzunluklar ve konumlar için ±1 ila ±1,5 mm.

Tek başına IoU yeterli değildir. Bunu kaba bir sayı buluyorum ve iki katıyı karşılaştıran daha basit bir şey olmadığı için kullanmaya devam ediyorum. Düz, deliksiz ve uzun deliksiz bir L bile 0,96’nın üzerinde puan alır; referanstan %20 büyük yapılmış doğru parça, her ikisi de aynı boyuta ölçeklendiğinde kusursuz 1,0 alır.

Bu yüzden burada her puan 13 geçti/kaldı kontrolüyle birlikte gelir. Kusursuz 1,0 bile, iki katının yalnızca o ızgarada eşleştiği anlamına gelir; mikron düzeyinde değil; ayrıca bu sayıların hiçbiri imalat garantisi değildir.

Kimi K3.1 Pro ile Görüntülerden CadQuery Kodu Üretin

İlk aday, araçsız tek bir istekten gelir ve döndürüldüğü gibi çalışır.

Dört referans görünümü Kimi K3.1 Pro API’sine gönderin

Kimi’nin görsel girdisi content dizisi içinde base64 veri URL’lerini alır ve herkese açık görsel URL’lerini kabul etmez. Sistem komutu, az önce anlattığım kadraj ve adlandırma kurallarını tutar; kullanıcı mesajı ise dört PNG’yi ve şu istemi taşır:

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.Altyapı:

İstekin kendisi kısadır:

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,
)Altyapı:

Ödeme yapmadan önce giriş boyutunu kontrol etmek için aynı mesajları jeton tahmin uç noktasına gönderin; tahmin fatura ile neredeyse birebir eşleşti. 512 piksellik dört görüntü 2.000’in altında giriş jetonuna gelir.

İlk CadQuery programını bir korumalı alanda çalıştırın

Çalıştırıcı, kodu bir çizik klasörüne yazar ve docker run komutuyla tek kullanımlık bir konteyner başlatır:

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)Altyapı:

İlk denemede Kimi’nin yanıtı yaklaşık bir dakika sürdü. Programı, gizli referanstaki tüm boyutları, bracket_depth = 40.0’tan slot_center_z = 25.5’e kadar adlandırdı. Geçerli bir katı üretti ve tüm kontrolleri geçti.

Aynı kamera, aynı ölçek, eşleşen parçalar. Görsel: Yazar.

Mükemmel ilk deneme beni bir sızıntı var mı diye kontrol etmeye itti; fakat PNG’lerde meta veri yok ve hiçbir komutta gizli bir değer bulunmuyor. Sonucu açıklayan Kimi’nin kodu oldu. Braketi tanımlarken belirttiğim gibi, özellikler bir tasarımcının koyacağı yerlere oturuyordu; Kimi de öyle yaptı.

Kimi, özellik konumlarını orta noktalardan türetiyor. Görsel: Yazar.

Kimi K3.1 Pro ile Kendini Kontrol Eden, Araç Çağıran Bir Ajan Oluşturun

Araç çağıran bir ajan döngü içinde çalışır. Kimi bir araç ister, kodunuz onu çalıştırır ve sonuç, Kimi bitene kadar bir araç mesajı olarak geri gönderilir.

Her biri sert limitlere sahip üç faz. Görsel: Yazar.

CAD’i çalıştırmak, incelemek ve çizmek için araçları tanımlayın

İşte execute_cad şema olarak. Sabit bir formatta kısa bir sonuç döndürür; bir program başarısız olduğunda iz yığınının son birkaç satırını verir:

{"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"]}}}Altyapı:

render_cad, dört görüntüsünü araç mesajının içinde döndürür; bu, ajanik görme eğitimimizin Gemini ile kullandığı aynı tekrar-bakış desenidir. Kimi’nin dokümanları bunun bir örneğini göstermiyor; dolayısıyla gözlemlenen davranış olarak değerlendirin. Üç denemenin tamamında bir role: "tool" mesajı image_url parçaları taşıdı ve model bunları okudu.

Araç döngüsünde tam asistan mesajını koruyun

Burada üç detay önemlidir ve ilk ikisi Kimi’nin düşünme modelleri kılavuzu ve hızlı başlangıcından gelir:

• Her turda tam asistan mesajını, reasoning_content ve tool_calls dahil, geri gönderin

• Her araç çağrısı için, eşleşen tool_call_id ile bir araç mesajı ekleyin

• OpenAI SDK’da tipli bir reasoning_content alanı olmadığından mesajı model_dump() ile serileştirin

Aşağıdaki döngü, üçünü de uygular:

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})Altyapı:

Buradaki bir hatayı yakalamak için API’ye güvenmeyin. Geçmişten reasoning_content kaldırılmış bir istek yine de başarılı olur; oysa dokümanlar alanı şart koşar ve onu düşürmek sonraki turların nasıl devam ettiğini değiştirebilir. Sessizce başarısız olan bir hatadan ziyade 400 tercih ederdim.

Bütçe döngünün kodunda yaşar; Kimi bunu değiştiremez. Üç onarım tükendiğinde execute_cad bir hatayla yanıt verir ve submit_cad tek bir geçerli katı olmayan her şeyi reddeder.

Onarım aşamasında ne oldu

Pek bir şey olmadı ve neredeyse bu bölümü bu yüzden kesiyordum. Onarım döngüsünü asıl işi yapar diye kurmuştum; Kimi ise ona zor dokundu. İlk adayını inceledi, çizdi, dört referans görünümüyle eşleştiğini söyleyen kendinden emin bir özet yazdı ve başladığı programı aynen gönderdi.

Bu özet her zaman doğru değildi. Bir denemede inspect_cad 3,0 mm delik yarıçapı raporladı; yani referansta 6,5 mm olan yerde 6,0 mm delikler; Kimi yine de gönderdi. Yarım milimetre bu görünümlerde 3 pikselin altındadır (ben de çıplak gözle bu boyutta güvenmezdim) ve geri bildirimin hiçbir yerinde doğru çapın ne olduğu yazmıyordu.

Araç 3,0 mm yarıçaplar raporladı. Görsel: Yazar.

Kimi K3.1 Pro ile Parametrik Bir CAD Modelini Düzenleyin

Onarım döngüsü atıl kalınca, tasarım değişikliği daha belirleyici test oldu. Yine de nazik bir test; aynı anda iki özelliği hareket ettiren bir değişiklik çok daha zorlayıcı olurdu.

Kimi’den uzun deliği genişletmesini isteyin

Düzenleme aynı konuşmayı sürdürür ve benim referans kodumdan değil, Kimi’nin gönderdiği adaydan başlar:

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.Altyapı:

Kimi, izin verilen 3 programından birini kullandı. Fark tek satırdır: slot_width = 6.0’dan slot_width = 9.0’a; sonra inceleme ve çizim için bir tur ve bir gönderim.

Düzenlemeyi dışa aktarılan geometri üzerinde kontrol edin

Koddaki yeni bir sayı, katının değiştiğini kanıtlamaz. Değerlendirici, izin verilen daha geniş uzun delik alanı dışındaki her şeyi göz ardı ederek, düzenleme öncesi ve sonrası katıları voksel voksel karşılaştırdı:

• Uzun delik 9 mm genişliğinde, aynı uzunlukta ve aynı merkezde
• Delikler, plaka kalınlığı ve dış boyutlar değişmedi
• Uzun delik alanı dışında hiçbir malzeme değişmedi

Her düzenleme kontrolü her seferinde geçti.

Düzenleme temiz çalıştı çünkü slot2D() uzunluğunu uçtan uca kabul eder; bu nedenle uzun delik 20 mm kaldı ve düz kısım kısaldı. İki yay merkezinin arasındaki mesafeyi saklayan bir program, uzun deliği 3 mm uzatırdı.

Düzenleme yalnızca uzun deliği değiştirdi. Görsel: Yazar.

Kimi K3.1 Pro CAD Ajanı Ne Kadar Doğruydu?

Ajan, üç denemenin tamamında, önceden sabitlediğim toleranslar içinde tüm gizli kontrolleri geçti. Aşağıdaki tabloyu bir özet olarak okuyun:

Üç deneme bir başarı oranı değildir; yalnızca sonucun bir braket üzerinde tuttuğunun göstergesidir. Onarım aşamasındaki 6,0 mm delikler sadece ±0,5 mm delik toleransına tam oturdukları için geçti; daha sıkı bir sınır o denemeyi başarısız kılardı.

Kendi kendini düzeltmenin düzeltecek bir şeyi yoktu

Döngünün bir modeli iyileştirip iyileştirmediğini gösterecek test bir hata-enjeksiyon koşusudur; ajanı bilinen hatalı bir programla başlatır. Onu bu denemelerden ayrı rapor ederdim.

Jeton maliyeti ve deneme başına çalışma süresi

Her deneme, altı istek ve yedi araç çağrısı için 6,3 ila 7,3 sent tuttu. Bu yalnızca API ücretleridir; çünkü çizim ve Docker benim makinemde çalıştı.

Her isteği usage alanlarından, yayınlanan tarifeler üzerinden kimi-k3.1-pro için fiyatlayın. Milyon jeton başına, girdi 2,00 $, çıktı 10,00 $, önbellek isabetleri 0,20 $ ve 5 dakikalık önbellek yazımları 2,00 $.

İlk istek en pahalıdır çünkü muhakeme Kimi’nin orada yaptığı şeydir. Çıktı faturanın yarısından fazlasını tutar ve önbellek yazımları %23 ila %35; önbellek isabetleri ise neredeyse hiçbir şeye mal olmaz. Üç giriş alanı nasıl toparlanır—az önce bağlantısını verdiğim Sohbet Tamamlamaları referansına göre—işte şöyle; izleyiciniz önbellek yazımlarını zaten ayırıyorsa bunu atlayabilirsiniz:

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) / 1e6Altyapı:

Muhakeme jetonları zaten completion_tokens içindedir; bu yüzden onları ikinci kez eklemeyin. 5 dakikalık bir önbellek yazımı, önbelleksiz girişle aynı fiyata gelir; bu nedenle istem önbellekleme ancak bir önek geri okunduğunda karşılığını verir. Araç döngüleri her turda aynı geçmişi yeniden gönderir ve burada önbellekleme, giriş faturasını düz oranın %40’ının altına düşürdü.

Bir deneme yaklaşık üç dakika sürer; çoğu beklemedir; çünkü istemci, SSS’lerde ele alacağım hız sınırı için istekleri 21 saniye arayla gönderir.

Görüntülerden Yapay Zekâ ile CAD Üretiminin Sınırları

Asıl sınır, görüntülerin her boyutu taşıyamamasıdır. Benim testim birkaç tane daha ekliyor:

• Oluşturulan görseller, bir pikselden küçük ayrıntıları gösteremez. Bir boyut önemliyse, onu metin olarak verin veya bir araçla ölçün.
• Braket tahmin etmesi kolaydı. Merkez dışı delikler ve tuhaf boyutlar, Kimi’nin pikselleri mi yoksa tasarım alışkanlıklarını mı okuduğunu test ederdi.
• Docker bayrakları yalnızca adları geçenleri engeller. Kurulum bölümündeki yaramaz programı durdurdular; ancak model kodu hâlâ tam bir dakikalık CPU’sunu yakabilir. Kapsayıcılarda yapay zekâ ajanlarını güvene alma rehberimiz sonraki katmanları kapsar.
• Bu kontrolleri geçmek dayanım hakkında hiçbir şey söylemez. Yük, malzeme, gerçek bir parçanın ihtiyaç duyacağı iç köşe yuvarlaması, cıvata uyumu ve toleransların toplamı bu testin dışındadır.

Kolay braket, Kimi’nin sınırından çok benim testimin sınırıdır.

Son Düşünceler

Dört görüntüden parametrik CadQuery kodu yazan, kendi katısını araçlarla kontrol eden ve istek üzerine bir özelliği düzenleyen bir ajan oluşturduk. Bu braket için, açılıştaki soruma yanıt evet. Üç denemenin hepsi, belirlediğim toleranslar içinde ilk istekte geçti ve uzun delik düzenlemesi parçanın geri kalanını olduğu gibi bıraktı.

Onarım döngüsü, kefil olamayacağım kısım; çünkü Kimi düzeltecek bir şey bulamadı. İncelemesi, pikselleri gördüğü—gerçek çapı asla görmediği—için 0,5 mm’lik tek hatayı geçirdi. Sonucu, tuhaf boyutlu bir parçaya veya gerçek bir parçanın fotoğraflarına genellemezdim.

Buradan taşınan, referansı gizleme, puanlama kurallarını ilk istekten önce dondurma ve kod yerine dışa aktarılan katıyı puanlama yöntemidir. Kimi adayı üç kez eşleşti dedi ve bunun iki kez doğru, bir kez yakın olduğunu söyleyebilen yalnızca değerlendiriciydi. Saklayacağım şey o değerlendiricidir ve ilk genişletmem bir hata-enjeksiyon koşusu olurdu.

Modelleri kendi araçlarınıza bağlama hakkında daha fazlası için, OpenAI API ile Yapay Zekâ Sistemleri Geliştirme kursumuz, bu ajanın kullandığı aynı SDK ile fonksiyon çağırmayı kapsar.