Tạo mô hình 3D có thể chỉnh sửa từ văn bản với Procedura

Procedura là gì?

Procedura là một quy trình tạo mô hình 3D tác tử, chuyển đổi câu lệnh văn bản thành một cụm lắp ráp tham số có thể chỉnh sửa. Thay vì chỉ tạo đám mây điểm hoặc lưới tam giác, công cụ này viết một chương trình OpenSCAD tham số, trong đó các bộ phận được đặt tên và kết nối với nhau thông qua các liên kết kiểu dữ liệu. Bạn có thể kiểm tra mã nguồn, chỉnh sửa rồi biên dịch lại.

Hệ thống sử dụng một mô hình ngôn ngữ lớn cố định và không cần dữ liệu huấn luyện 3D chuyên biệt. Một lần chạy có thể bắt đầu chỉ với văn bản, dựng lại một hình ảnh tham chiếu có sẵn hoặc tạo hình ảnh tham chiếu thông qua một mô hình hình ảnh được cấu hình riêng.

Procedura cũng có thể gán vật liệu PBR cho từng bộ phận bằng --paint và xuất các đối tượng có khớp chuyển động sang OpenUSD và URDF bằng --motion và --motion-urdf.

Tính năng chính

• Đầu ra quy trình có thể chỉnh sửa: Tạo mã nguồn OpenSCAD cùng với hình học đã biên dịch.
• Tạo theo từng bộ phận: Lập kế hoạch cho một đối tượng và xây dựng dần các thành phần có tên.
• Dựng lại từ hình ảnh tham chiếu: Chấp nhận hình ảnh có sẵn để cải thiện đáng kể độ trung thực.
• Phản hồi 3D: Có thể kết xuất bản dựng hiện tại trước khi tạo từng bộ phận mới.
• Mô hình hóa nhận biết cụm lắp ráp: Hỗ trợ các đặc điểm lắp ghép như chốt có kích thước danh nghĩa chung, ổ cắm, mẫu bu-lông và khớp gài.
• Tinh chỉnh lặp: Sử dụng các chu kỳ kết xuất, phê bình, vá lỗi và kiểm tra để cải thiện bản nháp.
• Vật liệu: Một bước xử lý dựa trên thị giác có thể gán màu sắc, độ kim loại và độ nhám cho từng bộ phận.
• Khớp chuyển động: Có thể lập kế hoạch chuyển động, xuất tệp OpenUSD và URDF, đồng thời tùy chọn xác thực vật lý trong NVIDIA Isaac Sim.
• Lần chạy có thể truy vết: Lưu câu lệnh, phản hồi, lệnh gọi công cụ, quyết định kiểm tra, bản kết xuất trung gian và các chỉnh sửa.
• Web Studio: Cung cấp giao diện trình duyệt để kết hợp các lần chạy và kiểm tra các sản phẩm đi kèm.

Điều kiện tiên quyết và cài đặt

Sao chép kho mã và chạy trình cài đặt các phần phụ thuộc:

git clone git@github.com:SpatiaOS/Procedura.git
cd Procedura
bash scripts/install-deps.sh

Trình cài đặt thiết lập Bun 1.3 trở lên, các gói của dự án, bản OpenSCAD hỗ trợ Manifold, Blender và tệp .env khởi đầu. Theo mặc định, Bun được đặt tại ~/.bun, OpenSCAD tại ~/opt/openscad và Blender tại ~/opt/blender/.

Tập lệnh có thể được chạy lại an toàn nhiều lần. Các thành phần đang hoạt động hiện có sẽ được giữ nguyên. Sử dụng các chế độ tùy chọn để kiểm tra phần phụ thuộc, bỏ qua Blender hoặc chọn tiền tố cài đặt khác:

bash scripts/install-deps.sh --check
bash scripts/install-deps.sh --no-blender
PREFIX=/opt bash scripts/install-deps.sh

--check báo cáo các yêu cầu còn thiếu mà không cài đặt bất cứ thứ gì. --no-blender bỏ qua việc tải Blender khoảng 350 MB, mặc dù Blender cần thiết cho một số tính năng kết xuất và phản hồi.

OpenSCAD phải hỗ trợ backend Manifold. Các gói cũ hơn của bản phân phối có thể chuyển sang CGAL và trở nên chậm hơn nhiều bậc độ lớn. Procedura kiểm tra --backend khi khởi động và thường từ chối sử dụng bản dựng không tương thích. Chỉ đặt PROCEDURA_ALLOW_CGAL_OPENSCAD=1 nếu bạn cố ý chấp nhận sự chậm trễ đó.

Trình cài đặt không cài NVIDIA Isaac Sim. Isaac Sim chỉ cần thiết cho việc xác thực vật lý liên quan đến quy trình chuyển động; các phần còn lại của Procedura hoạt động mà không cần nó. Trình cài đặt cũng giữ nguyên tệp .env hiện có.

Cấu hình endpoint LLM

Procedura không bao gồm khóa API hoặc backend suy luận được lưu trữ. Mở tệp .env đã tạo và cung cấp endpoint cùng khóa:

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
PROCEDURA_MODEL=gpt-5.2

Endpoint phải hỗ trợ POST {base}/chat/completions với các sự kiện do máy chủ gửi. Các lựa chọn tương thích có thể bao gồm API OpenAI, OpenRouter, cổng kết nối doanh nghiệp hoặc các máy chủ cục bộ dựa trên vLLM, Ollama hay LM Studio.

Việc chọn mô hình sử dụng một chuỗi, vì vậy bạn có thể dùng bất kỳ mã định danh mô hình nào được endpoint đã cấu hình cung cấp. Các preset đã được kiểm chứng và quy tắc phân giải mô hình được ghi trong src/config/models.ts.

Sử dụng giao thức Gemini gốc

Để sử dụng Gemini thông qua đường dẫn GenAI gốc, hãy đặt GEMINI_API_KEY và GEMINI_BASE_URL, sau đó thêm tiền tố gemini: vào mã định danh mô hình:

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

Đường dẫn này cung cấp các tính năng gốc như thinkingConfig và các phần suy nghĩ hạng nhất.

Tạo hình ảnh tùy chọn

Procedura không gọi API hình ảnh trừ khi bạn cấu hình hoặc yêu cầu rõ ràng. Để bật hình ảnh tham chiếu được tạo, hãy thêm một mô hình hình ảnh:

PROCEDURA_IMAGE_MODEL=gpt-image-1

Mô hình hình ảnh sử dụng lại OPENAI_BASE_URL và OPENAI_API_KEY. Nếu không có --image hoặc mô hình hình ảnh được cấu hình, các lần chạy vẫn chỉ sử dụng văn bản và không tự ý phát sinh chi phí tạo hình ảnh.

Tạo mô hình đầu tiên

Thư mục đầu ra là bắt buộc. Cung cấp thư mục bằng -o hoặc --output, sau đó nhập câu lệnh văn bản:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "a brutalist brass daybed with tapered legs"

Quy trình mặc định này lập kế hoạch cho các thành phần, dựng từng thành phần một và tinh chỉnh hình dạng hoàn chỉnh. Quy trình chỉ sử dụng văn bản, không dùng API hình ảnh và không đưa Blender vào vòng lặp phác thảo theo từng bộ phận. Đây là cấu hình hữu ích với chi phí thấp nhất.

Để xem tất cả tùy chọn được hỗ trợ, hãy chạy:

bun run scripts/procedura.ts --help

Cải thiện độ trung thực bằng ảnh tham chiếu

Cung cấp ảnh tham chiếu là cải tiến độ trung thực lớn nhất được dự án xác định. Truyền một ảnh bạn đã có cùng với lời nhắc mô tả:

bun run scripts/procedura.ts -o outputs/daybed \
  --image ref.png \
  --prompt "a brass daybed with tapered legs"

Ngoài ra, bạn có thể tạo ảnh tham chiếu trong lần chạy này bằng cách chỉ định một mô hình hình ảnh:

bun run scripts/procedura.ts -o outputs/daybed \
  --image-model gpt-image-1 \
  --prompt "a brass daybed with tapered legs"

Với các mô tả dài khó đặt trong dấu ngoặc kép của shell, hãy lưu lời nhắc vào một tệp:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt-file my_prompt.txt

Chạy quy trình chất lượng đầy đủ

Một lần chạy đầy đủ có thể kết hợp tái dựng từ ảnh tham chiếu, phản hồi trực quan, các tính năng lắp ráp, vật liệu, chuyển động và ngân sách tinh chỉnh lớn hơn. Các kế hoạch lớn có thể cần giới hạn LLM dài hơn, vì vậy trước tiên hãy tăng cả hai biến thời gian chờ:

export PROCEDURA_LLM_TIMEOUT_MS=1800000
export PROCEDURA_LLM_DEADLINE_MS=1800000

bun run scripts/procedura.ts -o outputs/gripper \
  --image gripper_ref.png \
  --3d-feedback \
  --assembly \
  --paint \
  --motion --motion-urdf \
  --max-steps 12 \
  --prompt "a two-finger parallel robot gripper"

Mỗi tùy chọn có một vai trò riêng:

• --3d-feedback cung cấp cho bộ tạo ảnh dựng của assembly hiện tại trước khi tạo từng bộ phận. Tùy chọn này thêm một lượt xử lý Blender cho mỗi bộ phận.
• --assembly thêm các giao diện lắp ghép thực tế thay vì chỉ dựa vào hình học chồng lấn.
• --paint dùng một lần gọi thị giác để gán các thuộc tính vật liệu PBR cho những bộ phận đã đặt tên.
• --motion lập kế hoạch khớp nối và xuất dữ liệu OpenUSD.
• --motion-urdf đồng thời tạo các tệp URDF và lưới cho từng liên kết.
• --max-steps 12 cho phép tối đa 12 chu kỳ tinh chỉnh. Mỗi chu kỳ thực hiện các thao tác dựng ảnh, phê bình, vá lỗi và kiểm tra, đồng thời tiêu tốn hai lần gọi LLM.

Các lần gọi lập kế hoạch kéo dài có thể cho thấy quy trình đang thực hiện công việc đáng kể. README khuyến nghị tăng thời gian chờ thay vì giới hạn PROCEDURA_MAX_PARTS, vì giới hạn số bộ phận sẽ đánh đổi chất lượng mô hình để lấy tốc độ.

Tiếp tục, phác thảo lại hoặc bỏ qua tinh chỉnh

Procedura có thể tiếp tục vòng lặp tinh chỉnh trong một thư mục đầu ra hiện có. Bỏ qua lời nhắc và chỉ định ngân sách bước mới:

bun run scripts/procedura.ts -o outputs/daybed --max-steps 12

Để loại bỏ bản phác thảo hiện có và tạo lại, hãy thêm --redo:

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "a brutalist brass daybed" \
  --redo

Dùng --no-refine khi bạn chỉ muốn bản phác thảo. Procedura sẽ chuyển bản phác thảo đó thành các tệp đầu ra cuối cùng. Với quy trình nguyên khối cũ, --one-shot thực hiện một lần gọi tạo mà không có giai đoạn lập kế hoạch và yêu cầu ảnh tham chiếu:

bun run scripts/procedura.ts -o outputs/daybed \
  --one-shot \
  --image ref.png \
  --prompt "a brutalist brass daybed"

Tìm hiểu thư mục đầu ra

Một lần chạy hoàn tất có thể chứa các tạo phẩm sau:

• image.png: Ảnh tham chiếu được cung cấp hoặc tạo ra.
• plan.json: Cấu trúc bộ phận đã được lập kế hoạch.
• _parts/NN_name/: Các tạo phẩm theo từng bộ phận dành cho quá trình tạo tăng dần.
• draft.scad và draft.obj: Mã nguồn thủ tục ban đầu và lưới đã biên dịch.
• final.scad và final.obj: Các sản phẩm bàn giao đã được tinh chỉnh.
• final_summary.txt: Kết luận cuối cùng và thông tin kết nối được bàn giao.
• preview_final/: Ảnh dựng với hiệu ứng che khuất môi trường của lưới cuối cùng bằng Blender.
• final_materials.json: Màu sắc, độ kim loại và độ nhám theo từng bộ phận được tạo bởi --paint.
• final_painted.scad, final_painted.obj và final_painted.mtl: Các tài sản mô hình đã được tô vật liệu.
• preview_painted/: Ảnh dựng PBR Cycles của mô hình đã tô vật liệu.
• motion/final_motion.usda: Đầu ra khớp nối OpenUSD.
• motion/urdf/ và motion/links/: Dữ liệu URDF và lưới theo từng liên kết khi được yêu cầu.
• _trajectory/procedura-id.jsonl: Lời nhắc, phản hồi, lần gọi công cụ và quyết định kiểm tra.
• _refine_steps/step_NNN/: Dữ liệu dựng ảnh, chẩn đoán, chỉnh sửa và biên dịch cho mỗi chu kỳ tinh chỉnh.

Mọi tệp OBJ do Procedura ghi đều được chuẩn hóa về một hộp giới hạn đơn vị. Việc xuất STL là tùy chọn và có thể bật bằng --export-stl.

Chạy lại vật liệu hoặc chuyển động độc lập

Việc tô vật liệu và xử lý chuyển động hoạt động trên thư mục của một lần chạy đã hoàn tất, vì vậy bạn có thể lặp lại một trong hai giai đoạn bằng mô hình khác hoặc sau khi xảy ra lỗi mà không cần tạo lại hình học:

bun run scripts/paint.ts RUN_DIRECTORY --model MODEL_KEY --refine-steps 2
bun run scripts/motion.ts RUN_DIRECTORY --model MODEL_KEY --urdf --no-validate

Cờ tùy chọn --no-validate bỏ qua bước xác thực chuyển động. Cờ này hữu ích khi không có Isaac Sim hoặc khi bạn chỉ cần các tệp khớp nối đã xuất.

Xử lý một tập dữ liệu

Đối với nhiều trường hợp, hãy dùng tập lệnh xử lý hàng loạt cùng với tệp lời nhắc JSON Lines:

bun run scripts/batch.ts \
  --prompts cases.jsonl --images \
  --incremental \
  --motion --validate --urdf \
  --max-steps 3 \
  --parallel 2 \
  --out-root outputs/batch_v1

Quy trình của bài báo tạo hình dạng và khớp nối đồng thời, sau đó tô màu riêng cho từng trường hợp đã hoàn thiện. Điều này ngăn lỗi tô màu làm mất hiệu lực của phần hình học đã hoàn tất:

bun run scripts/paint.ts outputs/batch_v1/CASE_ID

Giữ mức song song gần hai khi sử dụng --motion --validate, vì nhiều phiên bản Isaac Sim chạy không giao diện có thể làm cạn kiệt bộ nhớ GPU. Các lô chỉ tinh chỉnh có thể chịu được khoảng 8 đến 12 worker, nhưng mỗi chu kỳ đều khởi chạy Blender, vì vậy bộ nhớ có thể trở thành tài nguyên giới hạn trước giới hạn tốc độ API.

So sánh các tạo phẩm của lần chạy

Procedura tích hợp một máy chủ kết quả cục bộ để xem các bản kết xuất, tệp nguồn, số liệu và quỹ đạo của nhiều cấu hình cạnh nhau:

bun run scripts/results-server.ts \
  --root a=outputs/run_a \
  --root b=outputs/run_b

Tính năng này hữu ích khi thử nghiệm prompt, mô hình theo từng giai đoạn, ngân sách tinh chỉnh hoặc các tùy chọn như phản hồi 3D và tạo hình có nhận biết lắp ráp.

Sử dụng Procedura Studio

Studio là giao diện web cho cùng một quy trình. Công cụ cho phép bạn cấu hình một lần chạy với prompt, hình ảnh tham chiếu tùy chọn, các preset và tùy chọn điều khiển theo từng giai đoạn. Trong khi thực thi, bạn có thể theo dõi các bộ phận xuất hiện và kiểm tra kế hoạch, tạo phẩm của từng bộ phận, lịch sử tinh chỉnh, lưới 3D cuối cùng, vật liệu và khớp nối.

cd web
bun install
bun run start

Mở http://localhost:8080. Studio khởi chạy CLI từ thư mục gốc của kho lưu trữ và đọc cùng tệp .env, vì vậy không cần cấu hình API riêng.

Mẹo nâng cao

1. Bắt đầu với chi phí thấp, sau đó bổ sung các tính năng chất lượng. Xác thực endpoint và prompt bằng một lần chạy văn bản mặc định trước khi bật tính năng tạo hình ảnh, phản hồi trực quan, tô màu hoặc chuyển động.
2. Sử dụng hình ảnh tham chiếu thực khi có thể. Dự án xác định --image là cải thiện độ trung thực đơn lẻ lớn nhất.
3. Ghi đè mô hình theo từng giai đoạn. Sử dụng --agent-model, --scad-model, --paint-model hoặc --motion-model để chọn các khóa mô hình endpoint khác nhau cho từng giai đoạn.
4. Giữ lại hình học thành công. Chạy tô màu và chuyển động như các giai đoạn hậu xử lý riêng biệt khi lỗi không nên buộc phải dựng lại toàn bộ.
5. Theo dõi bộ nhớ trong các lần chạy song song. Blender và Isaac Sim có thể tiêu thụ đáng kể bộ nhớ ngay cả khi endpoint API của bạn có thể xử lý nhiều yêu cầu đồng thời hơn.
6. Kiểm tra quỹ đạo khi gỡ lỗi. Quỹ đạo JSONL và các thư mục tinh chỉnh theo từng bước cho thấy prompt, phản hồi của mô hình, các chỉnh sửa, kết quả biên dịch và quyết định của các cổng kiểm tra.
7. Xác nhận khả năng hỗ trợ của backend OpenSCAD. Nếu quá trình tạo hình có vẻ bị treo, hãy kiểm tra để chắc chắn Procedura đang sử dụng OpenSCAD có hỗ trợ Manifold thay vì bản dựng cũ chỉ dùng CGAL.

Kết luận

Procedura kết hợp việc lập kế hoạch bằng mô hình ngôn ngữ với CAD thủ tục, biên dịch lưới, tinh chỉnh trực quan, vật liệu và khớp nối tùy chọn. Hãy bắt đầu với một endpoint đã cấu hình và prompt văn bản đơn giản, sau đó bổ sung hình ảnh tham chiếu, phản hồi 3D, các tính năng lắp ráp, tô màu và chuyển động khi yêu cầu chất lượng tăng lên. Vì sản phẩm chính là mã nguồn có thể chỉnh sửa, các đối tượng tạo ra vẫn có thể được kiểm tra và tái sử dụng sau khi tạo.

Procedura được cấp phép MIT. Tài liệu dự án, bài báo và các thông tin bổ sung có tại trang dự án Procedura.