Samouczek API Kimi K3.1 Pro: zbuduj samosprawdzającego agenta 3D CAD w Pythonie

Użyj API Kimi K3.1 Pro, aby zbudować agenta obraz→CAD

Agent obraz→CAD zamienia zdjęcia części w edytowalny model CAD.

Dlaczego Kimi K3.1 Pro i CadQuery pasują do obraz→CAD

Kimi K3.1 Pro potrafi odczytać cztery obrazy, a potem zareagować na to, co wytworzy jego własny kod. Ten sam blog Moonshota, o którym wspominałem, podaje 92,7% z narzędziami i 72.8% bez na zadaniu Vision2Code BenchCAD, które ocenia kod CAD pisany na podstawie renderowanych widoków części. Te liczby pochodzą z podzbioru 1000 przypadków przy wysiłku max, a wynik z narzędziami używał harnessu Claude Code harness, więc część wyniku może należeć do harnessu.

Benchmark też wysyła wszystkie cztery widoki w jednym obrazie i skaluje każdą część do tego samego rozmiaru przed oceną. U mnie trafiają cztery osobne widoki plus jeden rzeczywisty wymiar przy wysiłku high, więc potraktuj liczbę Moonshota jako powód, by uruchomić test, a nie jako jego wynik. Gdy prowadziłem te próby, otwarte wagi nie były jeszcze do pobrania.

CadQuery to format wyjściowy, bo skrypt CadQuery sam w sobie jest modelem parametrycznym. Otwór to wywołanie z podaniem średnicy i pozycji, więc późniejsza edycja zmienia jedną liczbę i bryła się przebudowuje. Plik STL daje trójkąty i nie ma tam slot_width do zmiany.

Co agent widzi, a co pozostaje ukryte

Kimi dostaje cztery obrazy referencyjne, szerokość 60 mm i prompt systemowy. Ten prompt ustala milimetry i osie, centruje część w X i Y z dołem na Z=0 oraz prosi o nazwane wymiary i finalną bryłę w result.

Potem Kimi zna tylko to, co zgłoszą narzędzia. API Kimi nie uruchamia CadQuery, więc wszystkie cztery narzędzia żyją w aplikacji:

• execute_cad uruchamia program w kontenerze Dockera bez sieci i zapisuje wynik jako kandydata

• inspect_cad raportuje poprawność, liczbę brył, obwiednię, objętość i powierzchnie cylindryczne

• render_cad rysuje kandydata z tych samych czterech kamer co referencja

• submit_cad kończy fazę jednym kandydatem

Kimi nigdy nie widzi kodu referencyjnego ani żadnego wyniku. Ewaluator czyta zapisane pliki STEP dopiero po zakończeniu pracy agenta, więc wynik nie może sterować agentem ani go zatrzymać.

Wyniki nigdy nie wracają do Kimi. Obraz: autor.

Skonfiguruj API Kimi K3.1 Pro w Pythonie

Aby używać API Kimi K3.1 Pro w Pythonie, potrzebujesz czterech rzeczy. Wszystko testowałem na Linux x86_64 w tych wersjach:

• Klucz API Kimi z doładowaniem co najmniej 1 USD, zgodnie z szybkim startem K3.1 Pro

• Python 3.12.3 z openai 3.39.0, SDK OpenAI

• cadquery 2.8.0 do budowy i sprawdzania brył

• Docker 29.9.2 do piaskownicy

Poniższe fragmenty to wycinki z pełnego projektu w tym repozytorium GitHub, które za chwilę sklonujesz.

Zainstaluj CadQuery i zbuduj piaskownicę Dockera

Przewodnik instalacji CadQuery preferuje condę, choć pip na Pythonie 3.12 też działa. Sklonuj repozytorium i skonfiguruj je:

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/Obsługiwane przez

Obraz piaskownicy instaluje tę samą wersję CadQuery i działa jako zwykły użytkownik. Docker domyślnie nie ustawia limitów CPU ani pamięci, zgodnie z dokumentacją ograniczeń zasobów, więc ustawia je runner. Strona główna repozytorium wymienia polecenia do uruchomienia i oceny eksperymentu, w tym ścieżkę bez klucza API i Dockera.

Zanim kod Kimi trafi do kontenera, spróbuj go sam zepsuć. Mój program testowy próbował odczytać klucz API, połączyć się z siecią i zapisać poza swoim katalogiem roboczym — wszystkie trzy próby się nie powiodły.

Trzy zablokowane operacje w piaskownicy. Obraz: autor.

Wykonaj swoje pierwsze wywołanie API Kimi K3.1 Pro

To zwykłe SDK OpenAI skierowane na endpoint Moonshota. Ustawiaj reasoning_effort przy każdym żądaniu, bo domyślnie jest max i nie da się „wyłączyć myślenia”.

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))Obsługiwane przez

Pomiń temperature, top_p, n i obie kary, które w quickstarcie są stałe. Nawet taka jednozdaniowa odpowiedź zużywa większość tokenów completion na rozumowanie, więc dobierz limit z myślą o tym.

Jedno żądanie potwierdza klucz i model. Obraz: autor.

Jeśli API Kimi jest dla ciebie nowe, mój wcześniejszy samouczek Kimi K3 omawia streaming, wywoływanie narzędzi, cache i wejście wizji.

Utwórz referencyjny model CAD i cztery widoki testowe

Referencyjny model CAD to twój klucz odpowiedzi, więc każdy wynik ma do czego porównać. Swój zablokowałem przed pierwszym żądaniem — od kamer po zasady oceny — i niczego nie zmieniłem po obejrzeniu wyników.

Zdefiniuj wymiary kątownika

Kątownik to L, z pionową płytą dołączoną z tyłu podstawy. Jego początek układu (origin) leży na środku dolnej płaszczyzny, z osią X wzdłuż szerokości, przodem w stronę −Y i Z do góry:

Umieściłem rząd otworów i podłużny otwór na środku ich powierzchni i użyłem otworów 6,5 mm — typowego luzu dla M6 — bo tak byłoby w prawdziwym kątowniku. Ten wybór okazał się słabym punktem tego elementu i wyjaśnię dlaczego.

W funkcji budującej w, dep, h i t przechowują szerokość, głębokość, wysokość i grubość. Łączy dwie płyty i wycina cechy:

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)Obsługiwane przez

Skrypt sprawdza, czy jest jedna poprawna bryła oczekiwanego rozmiaru, zanim wyeksportuje plik STEP.

Wyrenderuj cztery widoki z ustalonymi kamerami

Niewielki renderer NumPy rysuje widoki: przód, góra, prawa i izometryczny, z tym samym stałym kadrowaniem dla referencji i każdego kandydata. Przy 512 px jeden piksel pokrywa ok. 0,19 mm, choć odczyt z obrazu może mylić się bardziej. Stałe kadrowanie sprawia też, że kandydat zbyt duży lub źle umiejscowiony wygląda źle zamiast się centrować.

Cztery obrazy wysyłane do Kimi. Obraz: autor.

Ustal zasady oceny przed uruchomieniem agenta

Ewaluator mierzy wyeksportowaną bryłę, więc nazwy parametrów go nie zwiodą. Tnie każdy plik STEP, aby znaleźć otwory, podłużny otwór i obie grubości płyt, a następnie oblicza voxel IoU — udział wspólnej objętości dwóch brył — na siatce 0,5 mm w rzeczywistej skali. Tolerancje odpowiadają skali piksela: ±0,5 mm dla grubości, średnic otworów i szerokości podłużnego otworu oraz ±1 do ±1,5 mm dla długości i pozycji odczytywanych z obrazów.

Samo IoU nie wystarcza. To dla mnie toporna liczba, a używam jej dalej, bo nic prostszego nie porównuje dwóch brył. Zwykłe L bez otworów i podłużnego otworu wciąż uzyska ponad 0,96, a poprawna część powiększona o 20% dostanie idealne 1,0 po przeskalowaniu obu do tego samego rozmiaru.

Dlatego każdy wynik tutaj ma 13 testów zalicz/nie zalicz. Nawet idealne 1,0 znaczy tylko, że dwie bryły zgadzają się na tej siatce, nie co do mikrometra, i żadna z tych liczb nie jest gwarancją produkcyjną.

Generuj kod CadQuery z obrazów za pomocą Kimi K3.1 Pro

Pierwszy kandydat powstaje z jednego żądania bez narzędzi i uruchamia się dokładnie tak, jak przyszedł.

Wyślij cztery widoki referencyjne do API Kimi K3.1 Pro

Wejście wizji Kimi przyjmuje adresy data URL w base64 wewnątrz tablicy content i nie akceptuje publicznych URL-i obrazów. Prompt systemowy zawiera zasady kadrowania i nazewnictwa, o których pisałem, a wiadomość użytkownika niesie cztery PNG i ten 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.Obsługiwane przez

Samo żądanie jest krótkie:

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,
)Obsługiwane przez

Aby sprawdzić rozmiar wejścia przed płatnością, wyślij te same wiadomości do endpointu szacowania tokenów, którego oszacowanie niemal idealnie zgadzało się z rachunkiem. Cztery obrazy 512 px to mniej niż 2000 tokenów wejściowych.

Uruchom pierwszy program CadQuery w piaskownicy

Runner zapisuje kod do katalogu tymczasowego i uruchamia jednorazowy kontener poleceniem 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)Obsługiwane przez

W pierwszej próbie odpowiedź Kimi zajęła około minuty. Jego program nazwał każdy wymiar z ukrytej referencji — od bracket_depth = 40.0 po slot_center_z = 25.5. Powstała poprawna bryła i przeszła każdy test.

Ta sama kamera, ta sama skala, zgodne części. Obraz: autor.

Idealna pierwsza próba sprawiła, że szukałem wycieku, ale PNG nie niosą metadanych, a żaden prompt nie zawiera ukrytej wartości. Kod Kimi wyjaśnia wynik. Jak wspomniałem przy definiowaniu kątownika, cechy leżą tam, gdzie umieściłby je konstruktor — i tak samo zrobił Kimi.

Kimi wyprowadza pozycje cech ze środków. Obraz: autor.

Zbuduj samosprawdzającego agenta wywołującego narzędzia z Kimi K3.1 Pro

Agent wywołujący narzędzia działa w pętli. Kimi prosi o narzędzie, twój kod je uruchamia, a wynik wraca jako wiadomość narzędzia, aż Kimi skończy.

Trzy fazy, każda z twardymi limitami. Obraz: autor.

Zdefiniuj narzędzia do uruchamiania, inspekcji i renderowania CAD

Oto execute_cad jako schemat. Zwraca krótki wynik w stałym formacie, z ostatnimi liniami stack trace, gdy program się nie powiedzie:

{"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"]}}}Obsługiwane przez

render_cad zwraca swoje cztery obrazy wewnątrz samej wiadomości narzędzia — ten sam wzorzec „spójrz ponownie”, którego używa nasz samouczek wizji agentowej z Gemini. Dokumentacja Kimi nie pokazuje tego przykładu, więc potraktuj to jako zachowanie zaobserwowane. We wszystkich trzech próbach wiadomość role: "tool" niosła części image_url i model je czytał.

Zachowaj pełną wiadomość asystenta w pętli narzędzi

Liczą się tu trzy szczegóły, a dwa pierwsze pochodzą z przewodnika Kimi o modelach myślących i quickstartu:

• Odsyłaj pełną wiadomość asystenta przy każdym kroku, łącznie z reasoning_content i tool_calls

• Dodaj jedną wiadomość narzędzia na każde wywołanie narzędzia, z pasującym tool_call_id

• Serializuj wiadomość przez model_dump(), bo SDK OpenAI nie ma typowanego pola reasoning_content

Pętla poniżej stosuje wszystkie trzy:

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})Obsługiwane przez

Nie licz na to, że API wyłapie tu błąd. Żądanie z usuniętym reasoning_content z historii wciąż się powiedzie, choć dokumentacja wymaga tego pola, a jego pominięcie może zmienić dalsze kroki. Wolałbym 400 niż błąd, który cicho przepada.

Budżet żyje w kodzie pętli, gdzie Kimi nie może go zmienić. Gdy 3 naprawy się wyczerpią, execute_cad odpowiada błędem, a submit_cad odrzuca wszystko, co nie jest jedną poprawną bryłą.

Co wydarzyło się w fazie napraw

Niewiele, i prawie wyciąłem tę sekcję z tego powodu. Zbudowałem pętlę napraw, spodziewając się, że wykona większość pracy, a Kimi ledwie jej dotknął. Sprawdził pierwszego kandydata, wyrenderował go, napisał pewne podsumowanie, że pasuje do wszystkich czterech widoków referencyjnych, i złożył ten sam program, od którego zaczął.

To podsumowanie nie zawsze było trafne. W jednej próbie inspect_cad podał promień 3,0 mm dla otworu, czyli otwory 6,0 mm tam, gdzie referencja ma 6,5 mm, a Kimi i tak złożył. Pół milimetra to poniżej 3 pikseli w tych widokach (sam bym nie ufał oku przy tej skali), a w feedbacku nie było, jaka powinna być prawidłowa średnica.

Narzędzie zgłosiło promienie 3,0 mm. Obraz: autor.

Edytuj parametryczny model CAD z Kimi K3.1 Pro

Przy bezczynnej pętli napraw zmiana projektu stała się bardziej wymownym testem. To jednak łagodny test, a zmiana poruszająca dwie cechy naraz byłaby znacznie trudniejsza.

Poproś Kimi o poszerzenie podłużnego otworu

Edycja to ciąg dalszy tej samej rozmowy i start z kandydata złożonego przez Kimi, nie z mojego kodu referencyjnego:

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.Obsługiwane przez

Kimi użył jednego z 3 dozwolonych programów. Różnica to jedna linia — z slot_width = 6.0 na slot_width = 9.0 — potem jedno przejście na inspekcję i render oraz złożenie.

Sprawdź edycję na wyeksportowanej geometrii

Nowa liczba w kodzie nie dowodzi, że bryła się zmieniła. Ewaluator porównał bryły przed i po edycji woksel po woksela, ignorując tylko przestrzeń, którą może zająć szerszy podłużny otwór:

• Podłużny otwór ma 9 mm szerokości, tę samą długość i środek
• Otwory, grubość płyt i zewnętrzny rozmiar bez zmian
• Poza obszarem podłużnego otworu nie zmienił się żaden materiał

Każdy test edycji przeszedł, za każdym razem.

Edycja zadziałała czysto, bo slot2D() traktuje długość jako „od końca do końca”, więc otwór pozostał 20 mm długi, a część prosta się skróciła. Program, który przechowuje odległość między środkami dwóch łuków, wydłużyłby otwór o 3 mm.

Edycja zmieniła tylko podłużny otwór. Obraz: autor.

Jak dokładny był agent CAD Kimi K3.1 Pro?

Agent przeszedł każdy ukryty test we wszystkich trzech próbach, w ramach tolerancji ustalonych z góry. Tabela to podsumowanie:

Trzy próby to nie współczynnik sukcesu, tylko znak, że wynik utrzymał się na jednym kątowniku. Otwory 6,0 mm z fazy napraw przeszły tylko dlatego, że dokładnie mieściły się w tolerancji ±0,5 mm dla otworów — ostrzejszy limit oblałby tę próbę.

Autokorekta nie miała czego poprawiać

Test, który pokaże, czy pętla poprawia model, to uruchomienie z wstrzykniętą usterką — start agenta od programu z znanym błędem. Opisałbym to osobno względem tych prób.

Koszt tokenów i czas na próbę

Każda próba kosztowała 6,3–7,3 centa za sześć żądań i siedem wywołań narzędzi. To tylko opłaty API, bo renderowanie i Docker działały u mnie lokalnie.

Wyceń każde żądanie z jego pól usage według opublikowanych stawek dla kimi-k3.1-pro. Za milion tokenów to 2,00 USD za wejście, 10,00 USD za wyjście, 0,20 USD za trafienia z cache i 2,00 USD za zapisy cache 5-minutowe.

Najwięcej kosztuje pierwsze żądanie, bo tam Kimi rozumuje. Wyjście to ponad połowa rachunku, a zapisy cache 23–35%, podczas gdy trafienia cache kosztują prawie nic. Tak sumują się trzy pola wejściowe, zgodnie z referencją Chat Completions, którą linkowałem — możesz to pominąć, jeśli twój tracker już rozdziela zapisy 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) / 1e6Obsługiwane przez

Tokeny reasoning są już w completion_tokens, więc nie dodawaj ich drugi raz. 5‑minutowy zapis cache kosztuje tyle co niekeszowane wejście, więc cache promptów opłaca się dopiero, gdy prefiks jest odczytywany ponownie. Pętle narzędzi wysyłają tę samą historię co krok, i tutaj cache ściął rachunek za wejście do poniżej 40% stawki bazowej.

Próba trwa ok. trzy minuty, głównie czekania, bo klient rozstawia żądania co 21 sekund ze względu na limit, który opisuję w FAQ.

Gdzie AI do generowania CAD ze zdjęć ma braki

Główne ograniczenie jest takie, że obrazy nie niosą wszystkich wymiarów. Mój test dodaje kilka kolejnych:

• Rendery nie pokażą detali mniejszych niż piksel. Jeśli wymiar ma znaczenie, podaj go tekstem lub zmierz narzędziem.
• Kątownik łatwo było odgadnąć. Otwory poza środkiem i nietypowe rozmiary sprawdziłyby, czy Kimi czyta piksele, czy nawyki projektowe.
• Flagi Dockera blokują tylko to, co nazwane. Zatrzymały psujący się program z sekcji konfiguracji, ale kod modelu wciąż może spalić pełną minutę CPU. Nasz przewodnik po zabezpieczaniu agentów AI w kontenerach opisuje kolejne warstwy.
• Przejście tych testów nic nie mówi o wytrzymałości. Obciążenie, materiał, zaokrąglony wewnętrzny narożnik, którego potrzebowałaby prawdziwa część, pasowanie śrub i kumulacja tolerancji są poza tym testem.

Łatwy kątownik to ograniczenie mojego testu, bardziej niż Kimi.

Na zakończenie

Zbudowaliśmy agenta, który na podstawie czterech obrazów pisze parametryczny kod CadQuery, sprawdza swoją bryłę narzędziami i na żądanie edytuje jedną cechę. Dla tego kątownika odpowiedź na moje pytanie otwierające brzmi: tak. Wszystkie trzy próby przeszły za pierwszym razem w ramach ustalonych tolerancji, a edycja podłużnego otworu zostawiła resztę części bez zmian.

Pętla napraw to część, za którą nie mogę ręczyć, bo Kimi nigdy nie znalazł nic do naprawy. Jego przegląd przepuścił ten jeden błąd 0,5 mm, bo widział piksele, a nie prawdziwą średnicę. Nie uogólniałbym wyniku na część o nietypowych rozmiarach ani na zdjęcia prawdziwej.

To, co warto przenieść, to metoda ukrycia referencji, zamrożenia zasad oceny przed pierwszym żądaniem i oceniania wyeksportowanej bryły zamiast kodu. Kimi trzy razy powiedział, że jego kandydat pasuje, i tylko ewaluator mógł stwierdzić, że dwa razy miał rację, a raz był blisko. Tego ewaluatora bym zachował, a pierwszym rozszerzeniem byłby test z wstrzykniętą usterką.

Więcej o łączeniu modeli z twoimi narzędziami znajdziesz w naszym kursie Developing AI Systems with the OpenAI API, który obejmuje wywoływanie funkcji z tym samym SDK, którego używa ten agent.