OpenAI-to-FreeCAD-workflow

자연어 설명을 3D CAD 모델로 변환하는 엔드 투 엔드 (end-to-end) 파이프라인입니다. 이 프로젝트는 고급 프롬프트 엔지니어링 (Prompt Engineering), 검색 증강 생성 (RAG, Retrieval-Augmented Generation), 그리고 퓨샷 러닝 (few-shot learning)을 활용하여 실행 가능한 FreeCAD Python 스크립트를 생성하며, 생성된 스크립트는 최종 3D 모델을 구축하고 시각화하는 데 사용됩니다.

이 프로젝트는 LLM (Large Language Models)이 어떻게 자연어와 CAD 소프트웨어 사이의 가교 역할을 하여, 비전문가도 3D 디자인에 접근할 수 있게 하고 프로토타이핑을 가속화할 수 있는지 보여줍니다.

자연어를 3D 모델로: 평이한 영어로 3D 객체를 설명하면 .stl 파일을 얻을 수 있습니다.
고급 프롬프트 엔지니어링 (Advanced Prompt Engineering): 2단계 프로세스를 통해 사용자의 일상적인 요청을 구조화되고 기계 친화적인 브리프 (brief)로 정제합니다.
하이브리드 RAG + 퓨샷 러닝 (Hybrid RAG + Few-Shot Learning): 파이프라인은 전문가가 작성한 코드 스니펫 (code snippets)으로 구성된 커스텀 지식 베이스 (RAG)를 사용하여 일반적인 AI 오류를 수정하며, 전체적인 스크립트 구조를 안내하기 위해 완전한 예시 (few-shot)를 함께 사용합니다.
헤드리스 FreeCAD 실행 (Headless FreeCAD Execution): 노트북은 생성된 스크립트를 실행하기 위해 커맨드 라인 버전의 FreeCAD를 설치하고 실행합니다.
자동 시각화 (Automatic Visualization): 최종 .stl 모델은 대화형 3D 뷰어와 6면 정투영 (6-view orthographic projection) 플롯 모두에 자동으로 표시됩니다.

이 프로젝트는 고품질의 신뢰할 수 있는 출력을 보장하기 위해 다단계 파이프라인을 따릅니다.

사용자 프롬프트 (User Prompt) -> [LLM] 프롬프트 정제기 (Prompt Refiner) -> 구조화된 브리프 (Structured Brief) -> [LLM] 코드 생성기 (Code Generator) (RAG + Few-Shot) -> FreeCAD 스크립트 -> [FreeCAD] 3D 모델 -> 시각화

간단히 말하면: 객체를 설명하면 → AI가 FreeCAD 스크립트를 작성하고 → 스크립트가 FreeCAD에서 실행되어 → 확인하거나 내보낼 수 있는 3D 모델을 얻게 됩니다.

초기 프롬프트 (Initial Prompt): 사용자가 원하는 3D 객체에 대한 자연어 설명을 제공합니다.
메타 프롬프팅 (Meta-Prompting): 첫 번째 LLM 호출이 "프롬프트 엔지니어 (Prompt Engineer)" 역할을 수행하여, 사용자의 텍스트를 정밀한 파라미터가 포함된 구조화되고 모호하지 않은 설계 요약(design brief)으로 변환합니다.
하이브리드 프롬프트 구성 (Hybrid Prompt Construction): 구조화된 설계 요약은 두 개의 고품질 완성형 예시 (퓨샷 학습 (few-shot learning)) 및 커스텀 지식 베이스에서 검색된 여러 개의 매우 관련성 높은 코드 스니펫 (RAG (Retrieval-Augmented Generation))과 결합됩니다. 이 "마스터 프롬프트 (master prompt)"는 AI에 필요한 모든 컨텍스트를 포함합니다.
코드 생성 (Code Generation): 마스터 프롬프트가 gpt-4o로 전송되며, gpt-4o는 실행 가능한 완전한 FreeCAD Python 스크립트를 생성합니다.
실행 (Execution): 노트북은 생성된 스크립트를 .py 파일로 저장하고, FreeCAD의 헤드리스 (headless) 버전을 사용하여 이를 실행하며, 이를 통해 최종 .stl 모델을 생성합니다.
시각화 (Visualization): 노트북은 .stl 파일을 로드하고 trimesh 라이브러리를 사용하여 이를 표시합니다.

이 프로젝트는 Google Colab에서 쉽게 실행되도록 설계되었지만, 선호에 따라 로컬 환경에서도 실행할 수 있습니다.

Colab에서 열기 (Open in Colab)

이 README 상단의 "Open in Colab" 배지를 클릭하세요. -
OpenAI API 키 추가 (Add Your OpenAI API Key)

다음 방법 중 하나를 사용하여 키를 제공할 수 있습니다:

• Colab (권장):

  • 왼쪽 사이드바에서 **열쇠 아이콘 (Secrets)**을 클릭합니다. - OPENAI_API_KEY라는 이름으로 새로운 Secret을 생성합니다. - 값을 키로 붙여넣고 "Notebook access"를 활성화합니다.

• 👉 대안: Secrets를 사용하는 대신, Colab에서 (폴더 아이콘 → 우클릭 → New file) .env 파일을 생성하고 다음 줄을 입력하거나, 셀에서 단순히 실행합니다: OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
%env OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

• 클릭합니다.

• 로컬 (선택 사항):

  • FreeCAD를 수동으로 설치합니다:
    • Ubuntu: sudo apt install freecad
    • macOS: brew install --cask freecad
    • Conda (크로스 플랫폼): conda install -c conda-forge freecad
  • Ubuntu:
    • .env.example을 .env로 복사합니다. - 텍스트 에디터로 .env를 열고 플레이스홀더를 실제 API 키로 교체합니다.

• FreeCAD 수동 설치:

Notebook 실행

• Colab에서는 모든 셀을 위에서 아래로 실행하기만 하면 됩니다.
• 로컬 환경에서는 Jupyter 또는 VS Code에서 notebook을 열고 동일하게 실행하세요.

AI & 프롬프팅 (Prompting): OpenAI API (GPT-4o), LangChain, 퓨샷 러닝 (Few-Shot Learning)
검색 증강 생성 (RAG): FAISS 벡터 스토어 (Vector Store)
CAD 엔진: FreeCAD
3D 시각화 (Visualization): Trimesh, Matplotlib
환경: Google Colab, Python

• OpenAI API 키 (platform.openai.com에서 생성)
• Python 3.9 이상
• FreeCAD 0.21 이상 (Colab에서는 자동으로 설치되며, 로컬 사용 시에는 수동으로 설치해야 함)

이 프로젝트는 연구용 프로토타입입니다. AI가 생성한 FreeCAD 코드를 헤드리스 서브프로세스 (freecadcmd)에서 실행합니다.

인라인 (inline) 코드를 실행하는 것보다 안전하지만, 민감한 환경이나 운영 (production) 환경에서 사용하기 전에 생성된 스크립트를 반드시 검토하십시오.

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.