Kimi K3.1 Pro APIチュートリアル：Pythonで自己チェック型3D CADエージェントを構築

Kimi K3.1 Pro APIで画像からCADへ変換するエージェントを作る

画像からCADへのエージェントは、部品の写真を編集可能なCADモデルに変換します。

Kimi K3.1 ProとCadQueryが画像→CADに適している理由

Kimi K3.1 Proは4枚の画像を読み、自分のコードが生む結果に反応できます。先に触れたMoonshotの同ブログでは、ツールありで92.7%、ツールなしで72.8%をBenchCADのVision2Codeタスクで報告しています。これは、部品のレンダリングビューから書かれたCADコードを採点するものです。数値は1,000件のサブセットでのmax努力設定におけるもので、ツールありのスコアはClaude Codeのハーネスを使っているため、スコアの一部はハーネスに起因する可能性があります。

また、このベンチマークは4つのビューを1枚の画像にまとめ、採点前に全パーツを同じ大きさへスケーリングします。私の方法では、4つのビューを別々に送り、実寸の1つの寸法を与え、highの努力設定で行います。したがって、Moonshotの数値は「再現試験を行う動機」と捉え、結果そのものとは切り分けてください。私が試した時点ではオープンウェイトは未配布でした。

CadQueryを出力形式に選ぶのは、CadQueryスクリプト自体がパラメトリックモデルだからです。穴は径と位置を持つ呼び出しであり、後の編集は数値を1つ変えるだけでソリッドが再構築されます。STLは三角形の集合で、変更すべきslot_widthは存在しません。

エージェントに見せるもの、隠すもの

Kimiには4枚の参照画像、60 mmの幅、そしてシステムプロンプトを与えます。プロンプトでは単位をミリ、軸方向を固定し、部品のX・Y中心配置とZ=0での底面位置を指定し、名前付き寸法とresultへの最終ソリッドの代入を求めます。

その後は、Kimiはツールが報告する情報しか知りません。KimiのAPI自体はCadQueryを実行しないため、4つのツールはすべてアプリケーション側にあります。

• execute_cad はネットワークなしのDockerコンテナでプログラムを実行し、結果を候補として保存

• inspect_cad は有効性、ソリッド数、バウンディングボックス、体積、円筒面を報告

• render_cad は参照と同じ4つのカメラから候補を描画

• submit_cad はその段階を1つの候補で終了

Kimiは参照コードやスコアを一切見ません。評価器はエージェントの終了後に保存されたSTEPファイルだけを読み取るため、スコアがエージェントを誘導・中断することはありません。

スコアはKimiに戻りません。画像：筆者作成。

PythonでKimi K3.1 Pro APIをセットアップする

Kimi K3.1 Pro APIをPythonで使うには4つが必要です。以下の環境で検証しました（Linux x86_64）：

• K3.1 Proクイックスタートにあるとおり、最低$1チャージ済みのKimi APIキー

• Python 3.12.3 と OpenAI SDK（openai 3.39.0）

• cadquery 2.8.0（ソリッドの構築と検査用）

• Docker 29.9.2（サンドボックス用）

以下のスニペットは、このGitHubリポジトリの完全版プロジェクトからの抜粋です。次にクローンします。

CadQueryをインストールし、Dockerサンドボックスを構築する

CadQueryのインストールガイドはcondaを推奨していますが、Python 3.12上のpipでも動作します。リポジトリをクローンしてセットアップします。

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/提供：

サンドボックスのイメージは同じCadQueryバージョンをインストールし、通常ユーザーで実行します。DockerはデフォルトでCPUやメモリ制限を設定しない（リソース制約ドキュメント参照）ため、ランナー側で制限を設定します。実験の実行や採点コマンドは、APIキーやDocker不要の経路も含め、リポジトリのトップに記載しています。

Kimiのコードがコンテナに届く前に、まず自分で壊してみてください。私のテストプログラムはAPIキーの読み取り、ネットワークアクセス、作業フォルダ外への書き込みを試みましたが、いずれも失敗しました。

サンドボックスでブロックされた3つの操作。画像：筆者作成。

最初のKimi K3.1 Pro API呼び出しを行う

これはOpenAI SDKをMoonshotのエンドポイントに向けた通常利用です。すべてのリクエストでreasoning_effortを設定してください。省略するとmaxとなり、思考をオフにはできません。

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))提供：

temperature、top_p、n、および両方のペナルティは指定不要です（クイックスタートでは固定値）。1文回答でも完了トークンの多くを推論が消費するため、その前提で上限を設定してください。

1回のリクエストでキーとモデルを確認。画像：筆者作成。

Kimi APIが初めてなら、Kimi K3チュートリアルでストリーミング、ツール呼び出し、キャッシュ、ビジョン入力を解説しています。

参照CADモデルと4つのテストビューを作成する

参照CADモデルは解答例に相当し、すべての採点で正確な比較対象となります。私は最初のリクエスト前に、カメラから採点規則まで全てを固定し、結果を見た後も一切変更しませんでした。

ブラケットの寸法を定義する

ブラケットはL字で、立ち上がり部はベースの背面側に接合されています。原点は底面の中央にあり、Xが幅方向、前方が−Y、Zが上方向です。

穴列とスロットはそれぞれの面の中央に配置し、穴径は6.5 mm（一般的なM6クリアランス）にしました。実物のブラケットもそうするはずです。この選択が、このブラケットの弱点になりました。その理由は後述します。

ビルド関数内では、w、dep、h、tが幅・奥行き・高さ・厚みを表します。2枚の板を結合し、フィーチャを切り抜きます。

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)提供：

スクリプトは、期待通りのサイズを持つ有効な単一ソリッドであることを確認してから、STEPファイルにエクスポートします。

固定カメラで4ビューをレンダリングする

小さなNumPyレンダラで、参照・候補とも同じ固定フレーミングの正面・上面・右側面・アイソメを描画します。512 pxでは1ピクセルは約0.19 mmに相当しますが、画像からの読み取りはそれ以上の誤差が出ることもあります。固定フレーミングにより、候補が大きすぎたり位置がずれている場合、再センタリングされず違和感が視覚に残ります。

Kimiに送った4枚の画像。画像：筆者作成。

エージェントの実行前に評価規則を固定する

評価器はエクスポートされたソリッドを測定するため、パラメータ名で誤魔化すことはできません。各STEPファイルをスライスして穴・スロット・両方の板厚を特定し、実寸0.5 mmグリッドでボクセルIoU（2つのソリッドの共通体積の割合）を計算します。許容差はピクセルスケールに合わせ、板厚・穴径・スロット幅は±0.5 mm、画像から読む長さ・位置は±1〜±1.5 mmとしました。

IoUだけでは不十分です。私はこの数値を荒い指標だと感じていますが、他に単純で確かなソリッド比較法がありません。穴やスロットのない単純なLでも0.96以上になり、正解品を20%拡大したものでも、双方を同スケールにしてしまえば1.0の満点になります。

そのため、本稿の各スコアには13個の合否チェックを添えています。1.0の満点であっても、そのグリッド上で一致したことを意味するだけで、ミクロン単位の一致ではありません。これらの数値はいずれも製造保証ではない点にご注意ください。

Kimi K3.1 Proで画像からCadQueryコードを生成する

最初の候補はツールなしの1回のリクエストで得て、そのまま実行します。

4つの参照ビューをKimi K3.1 Pro APIに送る

Kimiのビジョン入力は、content配列内のbase64データURLを受け取り、公開画像URLは受け付けません。システムプロンプトには先述のフレームと命名規則を入れ、ユーザーメッセージに4つのPNGと次のプロンプトを載せます。

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.提供：

リクエスト自体は短いものです。

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,
)提供：

支払前に入力サイズを確認するには、同じメッセージをトークン見積もりエンドポイントに送ります。見積もりは請求とほぼ一致しました。512 pxの画像4枚で、入力トークンは2,000未満です。

最初のCadQueryプログラムをサンドボックスで実行する

ランナーはコードを作業フォルダに書き出し、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)提供：

初回トライアルでは、Kimiの返信に約1分かかりました。プログラムには、bracket_depth = 40.0からslot_center_z = 25.5まで、隠された参照の全寸法名が並びました。有効なソリッドを生成し、全チェックをパスしました。

同じカメラ、同じスケールで一致。画像：筆者作成。

一発合格だったので情報漏えいを疑いましたが、PNGにはメタデータがなく、プロンプトに隠し値もありません。Kimiのコードを読むと理由が分かります。先ほど寸法定義で述べたように、フィーチャは設計者が置きそうな位置にあり、Kimiも同様に推定しました。

Kimiはフィーチャ位置を中点から導出。画像：筆者作成。

Kimi K3.1 Proで自己チェックするツール呼び出しエージェントを構築

ツール呼び出しエージェントはループで動作します。Kimiがツールを要求し、あなたのコードがそれを実行し、結果をツールメッセージとして返し、Kimiが終了を宣言するまで続きます。

3つのフェーズ。それぞれにハードな上限。画像：筆者作成。

CADの実行・検査・描画ツールを定義する

以下はexecute_cadのスキーマです。固定形式の短い結果を返し、失敗時は末尾のトレースバック数行を返します。

{"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"]}}}提供：

render_cadはツールメッセージ内に4枚の画像を返します。これは、エージェント型ビジョンのチュートリアルでGeminiに用いた「もう一度見て」パターンと同様です。Kimiのドキュメントに事例は見当たりませんが、観測された挙動として扱ってください。3回のトライアルすべてで、role: "tool"メッセージにimage_url要素が含まれ、モデルはそれを読み取りました。

ツールループでアシスタントメッセージを完全に保持する

重要な点が3つあります。最初の2つはKimiの思考モデルガイドとクイックスタートに基づきます。

• 毎ターン、reasoning_contentとtool_callsを含め、アシスタントメッセージ全体を返す

• ツール呼び出しごとに1つのツールメッセージを追加し、対応するtool_call_idを付与

• OpenAI SDKには型付きのreasoning_contentフィールドがないため、model_dump()でメッセージを直列化

以下のループはこの3点に従っています。

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})提供：

ここでの誤りをAPIが必ずしも検出してくれるとは限りません。履歴からreasoning_contentを削除してもリクエストは成功します。ドキュメント上は必須であり、落とすと後続の継続に影響する可能性があります。静かに失敗するバグより、400を返して欲しいところです。

予算管理はループのコード側（Kimiからは変更不可）に置きます。3回の修正枠を使い切ると、execute_cadはエラーで応答し、submit_cadは有効な単一ソリッド以外を拒否します。

修正フェーズで起きたこと

ほとんど何も起きませんでした。そのため、この節を削ろうかと思ったほどです。修正ループが主役になると想定して構築しましたが、Kimiはほぼ手付かず。最初の候補を検査・描画し、4ビューと一致しているという自信満々のサマリーを書いて、最初のプログラムのまま提出しました。

そのサマリーは毎回正確ではありません。一度、inspect_cadが穴半径3.0 mm（つまり穴径6.0 mm、参照は6.5 mm）と報告したにもかかわらず、Kimiは提出しました。半ミリはこのビューで3ピクセル未満（私自身の目でも自信が持てない差）であり、フィードバックに正しい径は載っていませんでした。

ツールは半径3.0 mmを報告。画像：筆者作成。

Kimi K3.1 ProでパラメトリックCADモデルを編集する

修正ループが動かなかったので、設計変更のほうが本質的なテストになりました。とはいえ今回は穏当な変更であり、2つ以上のフィーチャが同時に動く変更なら、より厳しい試金石になります。

Kimiにスロット幅の拡大を依頼する

編集は同じ会話の続きとして行い、私の参照コードではなく、Kimiが提出した候補から開始します。

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.提供：

Kimiは許可された3本のプログラムのうち1本を使用しました。差分は1行、slot_width = 6.0からslot_width = 9.0への変更だけ。その後、検査と描画を1ターン、そして提出です。

エクスポートしたジオメトリで編集を確認する

コード中の数値が変わっても、ソリッドが変わった証拠にはなりません。評価器は、編集前後のソリッドをボクセル単位で比較し、広がるスロット領域だけを除外して確認しました。

• スロット幅は9 mmで、長さと中心は同一
• 穴、板厚、外形寸法は不変
• スロット領域の外では材料が一切変化していない

すべての編集チェックを、毎回パスしました。

今回きれいに通ったのは、slot2D()の長さが「端から端」定義だからです。スロットの全長20 mmは変わらず、直線部分が短くなりました。両円弧中心間距離を保存する実装だと、スロットは3 mm長くなっていたでしょう。

変更されたのはスロットだけ。画像：筆者作成。

Kimi K3.1 ProのCADエージェントはどれだけ正確だったか？

エージェントは3回のトライアルすべてで、事前に固定した許容差内で、隠しチェックをすべて通過しました。以下は要点のまとめです。

3回のトライアルは成功率の指標にはなりませんが、少なくともこのブラケットでは一貫した結果が得られたことを示します。修正フェーズでの6.0 mmの穴は、±0.5 mmの許容差ギリギリで通っただけで、より厳しい制限なら不合格でした。

自己修正は修正対象がなかった

ループがモデルを改善するかを示すには、既知の誤りを含むプログラムから開始するフォールトインジェクションが適切です。本稿とは別に報告したい内容です。

トークンコストと1トライアルあたりの実行時間

各トライアルは6回のリクエストと7回のツール呼び出しで、6.3〜7.3セントでした。これはAPI料金のみで、描画とDockerはローカル実行です。

各リクエストのusageフィールドを使い、公開レートの kimi-k3.1-proで価格を算出します。100万トークンあたり、入力$2.00、出力$10.00、キャッシュヒット$0.20、5分キャッシュ書き込み$2.00です。

最初のリクエストが最も高いのは、Kimiがそこで推論するからです。請求の半分超が出力で、キャッシュ書き込みは23〜35%、キャッシュヒットはごくわずか。先ほどのChat Completionsリファレンスに基づく3つの入力区分の合算は以下の通りです。トラッカーがキャッシュ書き込みを別管理しているなら読み飛ばせます。

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) / 1e6提供：

推論トークンはすでにcompletion_tokensに含まれているため、二重計上しないでください。5分キャッシュの書き込みは未キャッシュ入力と同額なので、プロンプトキャッシュはプレフィックスが再読込されるときに効きます。ツールループは毎ターン同じ履歴を送り直すため、ここでは入力の請求を素のレートの40%未満に抑えられました。

1回のトライアルは約3分です。主に待ち時間で、レート制限に合わせてクライアントが21秒間隔で送っているためです（FAQで解説）。

画像からのAI CAD生成の限界

最大の制約は、画像にすべての寸法を載せられないことです。私のテストではさらに以下が加わります。

• レンダリングはピクセルより小さな詳細を示せません。重要な寸法はテキストで与えるか、ツールで測ってください。
• このブラケットは推測が容易でした。オフセンターの穴や奇妙なサイズなら、Kimiがピクセルを読んでいるのか、設計慣行を当てているのかを見分けられます。
• Dockerのフラグは指定したものしかブロックしません。セットアップ節の暴れるプログラムは止められましたが、モデルのコードは1分のCPU枠を使い切ることは可能です。コンテナ内のAIエージェントを保護するガイドで次の層を解説しています。
• これらのチェックに合格しても、強度は保証されません。荷重、材質、実部品で必要な内R、ボルトの嵌合、寸法公差の足し合わせは本テストの範囲外です。

易しいブラケットであることは、Kimiの限界というより、このテストの限界です。

まとめ

4枚の画像からパラメトリックなCadQueryコードを書くエージェントを構築し、ツールで自分のソリッドを検査し、依頼に応じて1つのフィーチャを編集しました。本ブラケットでは、冒頭の問いへの答えは「YES」です。3回とも、設定した許容差内で初回リクエストで合格し、スロットの編集でも他の部分に影響はありませんでした。

一方で修正ループについては、Kimiが修正対象を見つけなかったため胸を張れません。0.5 mmの誤りを通してしまったのは、ピクセルしか見ておらず真の直径を知らないからです。特異なサイズの部品や実物写真に、この結果を一般化はしません。

汎用的に有用なのは、参照を隠し、最初のリクエスト前に採点規則を凍結し、コードではなくエクスポートしたソリッドを採点する手法です。Kimiは3回とも「一致」と述べましたが、評価器だけが2回は正解、1回は近似と判定できました。残すべきはこの評価器であり、次に行うべきはフォールトインジェクションです。

モデルを自前のツールに接続する方法については、Developing AI Systems with the OpenAI APIコースで、本エージェントと同じSDKを使ったファンクションコーリングを解説しています。