Hướng dẫn API Kimi K3.1 Pro: Xây dựng Agent CAD 3D tự kiểm bằng Python

Dùng API Kimi K3.1 Pro để xây dựng Agent chuyển ảnh thành CAD

Một agent chuyển ảnh thành CAD biến ảnh của một chi tiết thành mô hình CAD mà bạn có thể chỉnh sửa.

Vì sao Kimi K3.1 Pro và CadQuery phù hợp cho chuyển ảnh thành CAD

Kimi K3.1 Pro có thể đọc bốn ảnh rồi phản hồi theo những gì mã của chính nó tạo ra. Blog Moonshot tôi nhắc tới báo cáo 92,7% khi có công cụ và 72.8% khi không có trên nhiệm vụ Vision2Code của BenchCAD, đo điểm mã CAD viết từ ảnh render của một chi tiết. Những con số đó đến từ tập con 1.000 trường hợp ở mức nỗ lực max, và điểm khi có công cụ dùng bộ harness Claude Code, nên một phần điểm có thể đến từ harness.

Bài benchmark cũng gửi cả bốn góc nhìn trong một ảnh và co giãn mọi chi tiết về cùng kích thước trước khi chấm. Bên tôi gửi bốn góc nhìn tách rời cộng một kích thước thực ở mức high, nên hãy xem số của Moonshot như lý do để chạy thử thay vì coi là kết quả. Khi tôi chạy các lượt này, trọng số mở chưa thể tải xuống.

CadQuery được chọn làm định dạng đầu ra vì một script CadQuery tự nó là mô hình tham số. Một lỗ là một lời gọi với đường kính và vị trí, nên chỉnh sửa sau này chỉ thay đổi một con số và khối đặc sẽ dựng lại. File STL thì chỉ có tam giác, và không có slot_width để thay đổi.

Agent được thấy gì và điều gì bị ẩn

Kimi nhận bốn ảnh tham chiếu, bề rộng 60 mm, và một prompt hệ thống. Prompt đó cố định đơn vị milimét và các trục, căn chi tiết vào tâm theo X và Y với đáy tại Z=0, và yêu cầu các kích thước đặt tên cùng khối đặc cuối cùng trong biến result.

Sau đó, Kimi chỉ biết những gì công cụ báo về. API Kimi không chạy CadQuery, nên cả bốn công cụ đều nằm trong ứng dụng:

• execute_cad chạy một chương trình trong container Docker không có mạng và lưu kết quả làm bản ứng viên

• inspect_cad báo tính hợp lệ, số khối đặc, hộp bao, thể tích và các mặt trụ

• render_cad vẽ bản ứng viên từ bốn camera giống bản tham chiếu

• submit_cad kết thúc một pha với một bản ứng viên

Kimi không bao giờ thấy mã tham chiếu hoặc điểm số. Bộ chấm chỉ đọc các file STEP đã lưu sau khi agent hoàn tất, nên điểm không thể điều hướng hay dừng agent.

Điểm số không bao giờ quay lại Kimi. Ảnh: Tác giả.

Thiết lập API Kimi K3.1 Pro trong Python

Để dùng API Kimi K3.1 Pro trong Python, bạn cần bốn thứ. Tôi kiểm thử mọi thứ trên Linux x86_64 với các phiên bản sau:

• Một khóa API Kimi với tối thiểu 1 USD nạp thêm, theo hướng dẫn nhanh K3.1 Pro

• Python 3.12.3 với openai 3.39.0, SDK OpenAI

• cadquery 2.8.0 để dựng và kiểm tra khối đặc

• Docker 29.9.2 cho sandbox

Các đoạn dưới đây là trích đoạn từ dự án đầy đủ trong kho GitHub này, mà bạn sẽ clone ngay sau.

Cài CadQuery và dựng sandbox Docker

Hướng dẫn cài đặt của CadQuery ưu tiên conda, dù pip trên Python 3.12 cũng chạy được. Hãy clone kho và thiết lập:

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/Được hỗ trợ bởi

Ảnh sandbox cài đúng phiên bản CadQuery và chạy dưới quyền người dùng thường. Docker mặc định không đặt giới hạn CPU hay bộ nhớ, theo tài liệu giới hạn tài nguyên, nên trình chạy sẽ đặt chúng. Trang chính của kho liệt kê các lệnh để chạy và chấm thí nghiệm, bao gồm cả một luồng không cần API key hay Docker.

Trước khi mã của Kimi chạy trong container, hãy tự thử phá nó. Chương trình kiểm thử của tôi cố đọc khóa API, truy cập mạng và ghi ra ngoài thư mục tạm, cả ba đều thất bại.

Ba thao tác bị chặn trong sandbox. Ảnh: Tác giả.

Thực hiện cuộc gọi API Kimi K3.1 Pro đầu tiên

Đây là SDK OpenAI thông thường trỏ vào endpoint của Moonshot. Đặt reasoning_effort trên mọi yêu cầu, vì nếu bỏ qua sẽ là max, và bạn không thể tắt suy luận.

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))Được hỗ trợ bởi

Bỏ qua temperature, top_p, n và cả hai khoản phạt, vì hướng dẫn nhanh ghi cố định. Ngay cả câu trả lời một câu như thế này cũng tiêu tốn phần lớn completion tokens cho suy luận, nên hãy đặt trần theo đó.

Một yêu cầu xác nhận khóa và model. Ảnh: Tác giả.

Nếu API Kimi còn mới với bạn, hướng dẫn Kimi K3 trước đó của tôi đề cập streaming, gọi công cụ, caching và đầu vào thị giác.

Tạo mô hình CAD tham chiếu và bốn góc nhìn kiểm thử

Mô hình CAD tham chiếu là đáp án của bạn, để mọi điểm số đều có thứ chính xác để so sánh. Tôi khóa mọi thứ trước yêu cầu đầu tiên, từ camera đến quy tắc chấm điểm, và không thay đổi gì sau khi xem kết quả.

Định nghĩa kích thước giá đỡ

Giá đỡ hình chữ L, với phần thẳng đứng nối ở phía sau đế. Gốc tọa độ nằm ở tâm của mặt đáy, trục X theo chiều rộng, mặt trước hướng về −Y, và Z hướng lên:

Tôi đặt hàng lỗ và rãnh vào giữa mặt của chúng và dùng lỗ 6,5 mm, kích cỡ hở thông dụng cho M6, vì một giá đỡ thực tế sẽ như vậy. Lựa chọn đó hóa ra là điểm yếu của chi tiết này, và ta sẽ nói tại sao.

Trong hàm dựng, w, dep, h và t lần lượt là rộng, sâu, cao và dày. Chương trình nối hai tấm và cắt các đặc tính:

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)Được hỗ trợ bởi

Script kiểm tra có đúng một khối đặc hợp lệ với kích thước mong đợi trước khi xuất file STEP.

Render bốn góc nhìn với camera cố định

Một bộ render nhỏ dùng NumPy vẽ các góc nhìn chính diện, từ trên xuống, bên phải và đẳng phối với khung cố định giống nhau cho bản tham chiếu và mọi bản ứng viên. Ở 512 px, một pixel tương ứng khoảng 0,19 mm, dù phép đọc từ ảnh có thể sai hơn. Khung cố định cũng giúp ứng viên quá lớn hoặc đặt sai vị trí trông “sai” thay vì được căn giữa lại.

Bốn ảnh gửi cho Kimi. Ảnh: Tác giả.

Đặt quy tắc đánh giá trước khi chạy agent

Bộ chấm đo khối đặc đã xuất, nên tên tham số không thể đánh lừa. Nó cắt từng file STEP để tìm lỗ, rãnh và độ dày hai tấm, và tính IoU voxel, phần thể tích trùng nhau của hai khối, trên lưới 0,5 mm ở kích thước thực. Sai số bám theo thang pixel: ±0,5 mm cho độ dày, đường kính lỗ và bề rộng rãnh, và ±1 đến ±1,5 mm cho chiều dài và vị trí đọc từ ảnh.

Chỉ số IoU là chưa đủ. Tôi thấy nó khá thô, nhưng vẫn dùng vì không có thứ đơn giản hơn để so hai khối đặc. Một chữ L trơn không lỗ không rãnh vẫn đạt trên 0,96, và chi tiết đúng nhưng phóng to 20% vẫn đạt 1,0 hoàn hảo khi cả hai được co giãn về cùng kích thước.

Vì vậy mọi điểm số ở đây đều kèm 13 kiểm tra đạt/trượt. Ngay cả 1,0 hoàn hảo cũng chỉ nghĩa là hai khối khớp trên lưới đó, không phải đến từng micron, và không con số nào là bảo chứng sản xuất.

Sinh mã CadQuery từ ảnh bằng Kimi K3.1 Pro

Bản ứng viên đầu tiên đến từ một yêu cầu không dùng công cụ, và chạy đúng như trả về.

Gửi bốn góc nhìn tham chiếu đến API Kimi K3.1 Pro

Đầu vào thị giác của Kimi nhận data URL base64 bên trong mảng content, và không chấp nhận URL ảnh công khai. Prompt hệ thống chứa khung và quy tắc đặt tên như tôi mô tả, còn thông điệp người dùng mang bốn PNG và prompt sau:

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.Được hỗ trợ bởi

Bản thân yêu cầu khá ngắn:

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,
)Được hỗ trợ bởi

Để kiểm tra kích thước đầu vào trước khi trả phí, hãy gửi cùng các message tới endpoint ước tính token, và ước tính khớp gần như chính xác với hóa đơn. Bốn ảnh 512 px chiếm dưới 2.000 token đầu vào.

Chạy chương trình CadQuery đầu tiên trong sandbox

Trình chạy ghi mã vào thư mục tạm và khởi chạy container dùng một lần với lệnh 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)Được hỗ trợ bởi

Ở lượt đầu, phản hồi của Kimi mất khoảng một phút. Chương trình của nó đặt tên mọi kích thước giống tham chiếu ẩn, từ bracket_depth = 40.0 đến slot_center_z = 25.5. Nó tạo ra một khối đặc hợp lệ và vượt qua mọi kiểm tra.

Cùng camera, cùng tỉ lệ, chi tiết khớp nhau. Ảnh: Tác giả.

Một lần đúng hoàn hảo khiến tôi kiểm tra xem có rò rỉ nào không, nhưng các PNG không mang metadata, và không prompt nào chứa giá trị ẩn. Mã của Kimi giải thích kết quả. Như tôi đã nói khi định nghĩa giá đỡ, các đặc tính nằm ở vị trí mà một nhà thiết kế sẽ đặt, và Kimi cũng làm vậy.

Kimi suy ra vị trí đặc tính từ trung điểm. Ảnh: Tác giả.

Xây dựng agent gọi công cụ tự kiểm bằng Kimi K3.1 Pro

Một agent gọi công cụ chạy trong vòng lặp. Kimi yêu cầu một công cụ, mã của bạn chạy nó, và kết quả quay lại dưới dạng thông điệp công cụ cho đến khi Kimi xong.

Ba pha, mỗi pha có giới hạn cứng. Ảnh: Tác giả.

Định nghĩa công cụ để chạy, kiểm tra và render CAD

Đây là schema của execute_cad. Nó trả về kết quả ngắn theo định dạng cố định, kèm vài dòng cuối của traceback khi chương trình lỗi:

{"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"]}}}Được hỗ trợ bởi

render_cad trả về bốn ảnh ngay trong thông điệp công cụ, theo mẫu nhìn lại tương tự hướng dẫn agentic vision với Gemini. Tài liệu của Kimi không có ví dụ việc này, nên coi là hành vi quan sát được. Trong cả ba lượt, thông điệp role: "tool" mang phần image_url và model đọc được.

Giữ nguyên toàn bộ thông điệp assistant trong vòng lặp công cụ

Ba chi tiết quan trọng ở đây, và hai chi tiết đầu đến từ hướng dẫn mô hình suy luận và hướng dẫn nhanh của Kimi:

• Gửi lại toàn bộ thông điệp assistant ở mỗi lượt, bao gồm reasoning_content và tool_calls

• Thêm một thông điệp công cụ cho mỗi lời gọi công cụ, với tool_call_id tương ứng

• Tuần tự hóa thông điệp bằng model_dump(), vì SDK OpenAI không có trường reasoning_content kiểu hóa

Vòng lặp dưới đây tuân thủ cả ba:

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})Được hỗ trợ bởi

Đừng trông chờ API phát hiện lỗi ở đây. Một yêu cầu mà reasoning_content bị loại khỏi lịch sử vẫn thành công, dù tài liệu yêu cầu trường này, và bỏ nó có thể thay đổi cách các lượt sau tiếp tục. Tôi muốn nhận 400 hơn là một lỗi âm thầm.

Ngân sách nằm trong mã vòng lặp, nơi Kimi không thể thay đổi. Khi đã dùng hết 3 lượt sửa, execute_cad sẽ trả về lỗi, và submit_cad từ chối mọi thứ không phải đúng một khối đặc hợp lệ.

Điều gì xảy ra trong pha sửa lỗi

Không nhiều, đến mức tôi suýt cắt phần này. Tôi xây vòng lặp sửa với kỳ vọng nó làm phần lớn công việc, nhưng Kimi hầu như không đụng. Nó kiểm tra bản ứng viên đầu, render, viết tóm tắt tự tin rằng nó khớp cả bốn góc nhìn tham chiếu, rồi nộp lại đúng chương trình ban đầu.

Tóm tắt đó không phải lúc nào cũng đúng. Trong một lượt, inspect_cad báo bán kính lỗ 3,0 mm, tức lỗ 6,0 mm trong khi tham chiếu là 6,5 mm, và Kimi vẫn nộp. Nửa milimét dưới 3 pixel trong các góc nhìn này (bản thân tôi cũng không tin mắt ở mức đó), và phản hồi không hề nói đường kính đúng là bao nhiêu.

Công cụ báo bán kính 3,0 mm. Ảnh: Tác giả.

Chỉnh sửa mô hình CAD tham số bằng Kimi K3.1 Pro

Vì vòng lặp sửa lỗi gần như không hoạt động, thay đổi thiết kế trở thành bài thử quan trọng hơn. Dù vậy đây vẫn là phép thử nhẹ; thay đổi làm di chuyển hai đặc tính cùng lúc sẽ khó hơn nhiều.

Yêu cầu Kimi mở rộng rãnh

Lần chỉnh sửa tiếp tục trong cùng cuộc hội thoại và bắt đầu từ bản ứng viên Kimi đã nộp, không phải mã tham chiếu của tôi:

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.Được hỗ trợ bởi

Kimi dùng một trong 3 chương trình cho phép. Diff chỉ một dòng, từ slot_width = 6.0 thành slot_width = 9.0, rồi một lượt để kiểm tra và render, và nộp.

Kiểm tra chỉnh sửa trên hình học đã xuất

Một con số mới trong mã không chứng minh khối đặc đã đổi. Bộ chấm so sánh hai khối trước và sau chỉnh sửa theo voxel, chỉ bỏ qua phần không gian mà rãnh rộng hơn được phép chiếm:

• Rãnh rộng 9 mm, cùng chiều dài và tâm
• Lỗ, độ dày tấm và kích thước ngoài không đổi
• Không có vật liệu thay đổi ngoài vùng rãnh

Mọi kiểm tra chỉnh sửa đều đạt, mọi lần.

Việc chỉnh sửa chạy mượt vì slot2D() coi chiều dài là đầu–đầu, nên rãnh giữ 20 mm và phần thẳng ngắn lại. Một chương trình lưu khoảng cách giữa tâm hai cung sẽ làm rãnh dài hơn 3 mm.

Chỉ có rãnh thay đổi. Ảnh: Tác giả.

Độ chính xác của CAD agent Kimi K3.1 Pro ra sao?

Agent vượt qua mọi kiểm tra ẩn trong cả ba lượt, trong các dung sai tôi đặt trước. Hãy đọc bảng dưới như một bản tóm lược:

Ba lượt không phải là tỷ lệ thành công, chỉ là dấu hiệu kết quả ổn trên một giá đỡ. Lỗ 6,0 mm trong pha sửa chỉ qua được vì nó nằm đúng ở rìa dung sai ±0,5 mm cho lỗ; siết chặt hơn sẽ trượt lượt đó.

Tự sửa không có gì để sửa

Bài kiểm tra cho thấy vòng lặp có cải thiện mô hình hay không là chạy tiêm lỗi, tức khởi động agent từ một chương trình có lỗi đã biết. Tôi sẽ báo cáo riêng ngoài các lượt này.

Chi phí token và thời gian chạy mỗi lượt

Mỗi lượt tốn 6,3 đến 7,3 xu cho sáu yêu cầu và bảy lời gọi công cụ. Đó là phí API, vì render và Docker chạy trên máy tôi.

Tính giá mỗi yêu cầu từ các trường usage theo mức giá công bố cho kimi-k3.1-pro. Tính theo triệu token, đầu vào 2,00 USD, đầu ra 10,00 USD, cache hit 0,20 USD, và ghi cache 5 phút là 2,00 USD.

Yêu cầu đầu tốn nhiều nhất vì đó là nơi Kimi suy luận. Đầu ra chiếm hơn nửa hóa đơn và ghi cache 23% đến 35%, trong khi cache hit hầu như không đáng kể. Ba trường đầu vào cộng lại như sau, theo tài liệu tham chiếu Chat Completions tôi đã dẫn; bạn có thể bỏ qua nếu công cụ theo dõi của bạn đã tách phần ghi 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) / 1e6Được hỗ trợ bởi

Token suy luận đã nằm trong completion_tokens, nên đừng cộng lần hai. Ghi cache 5 phút có giá như đầu vào chưa cache, nên prompt caching chỉ đáng giá khi phần đầu được đọc lại. Vòng lặp công cụ gửi lại cùng lịch sử mỗi lượt, và ở đây caching giảm hóa đơn đầu vào xuống dưới 40% so với mức thông thường.

Một lượt mất khoảng ba phút, chủ yếu là đợi, vì client giãn cách yêu cầu 21 giây do giới hạn tốc độ tôi nêu trong phần Câu hỏi thường gặp.

Những điểm hạn chế của sinh CAD từ ảnh bằng AI

Giới hạn chính là ảnh không thể mang mọi kích thước. Bài kiểm thử của tôi bổ sung vài điểm nữa:

• Ảnh render không thể hiển thị chi tiết nhỏ hơn một pixel. Nếu một kích thước quan trọng, hãy cung cấp bằng văn bản hoặc đo bằng công cụ.
• Giá đỡ này dễ đoán. Lỗ lệch tâm và kích thước lạ sẽ kiểm tra xem Kimi đọc pixel hay thói quen thiết kế.
• Cờ Docker chỉ chặn những gì được nêu. Chúng dừng chương trình “gây rối” ở phần thiết lập, nhưng mã của model vẫn có thể đốt hết một phút CPU. Hướng dẫn về bảo mật agent AI trong container của chúng tôi đề cập các lớp tiếp theo.
• Vượt qua những kiểm tra này không nói gì về độ bền. Tải, vật liệu, góc lượn trong mà chi tiết thật cần, độ lắp bu lông và tích lũy dung sai nằm ngoài phạm vi này.

Giá đỡ đơn giản là giới hạn của bài test tôi hơn là của Kimi.

Kết luận

Chúng ta đã xây dựng một agent viết mã CadQuery tham số từ bốn ảnh, tự kiểm tra khối đặc bằng công cụ và chỉnh sửa một đặc tính theo yêu cầu. Với giá đỡ này, câu trả lời cho câu hỏi mở đầu của tôi là có. Cả ba lượt đều đạt ngay yêu cầu đầu tiên trong dung sai đã đặt, và chỉnh sửa rãnh không làm thay đổi phần còn lại.

Vòng lặp sửa là phần tôi chưa thể bảo chứng, vì Kimi không tìm thấy gì để sửa. Phần rà soát của nó cho qua lỗi 0,5 mm vì nó chỉ thấy pixel, không thấy đường kính thật. Tôi sẽ không khái quát kết quả này cho chi tiết kích thước lạ hoặc ảnh chụp ngoài đời.

Điều mang tính tổng quát là phương pháp ẩn tham chiếu, cố định quy tắc chấm điểm trước yêu cầu đầu tiên, và chấm trên khối đặc đã xuất thay vì trên mã. Kimi nói bản ứng viên khớp ba lần, và chỉ bộ chấm mới cho thấy hai lần đúng và một lần gần đúng. Tôi sẽ giữ bộ chấm đó, và chạy tiêm lỗi sẽ là mở rộng đầu tiên của tôi.

Để tìm hiểu thêm về việc kết nối model với công cụ của riêng bạn, khóa học Developing AI Systems with the OpenAI API của chúng tôi đề cập gọi hàm với cùng SDK mà agent này dùng.