개인 시뮬레이션 폴더를 다른 팀이 실제로 재사용할 수 있는 버전 관리된 환경으로 전환하기 위한 실무 가이드.

이 시리즈의 첫 번째 기사에서 우리는 로봇 학습 (Robot Learning)의 숨겨진 병목 현상은 알고리즘이 아니라 환경이라는 점을 주장했습니다. 공유된 장면 (Scenes), 공유된 계약 (Contracts), 그리고 공유된 평가 (Evaluation)가 진보를 복리로 만들어냅니다.

이 글은 가장 작으면서도 유용한 다음 단계입니다.

이미 자신의 머신에서 작동하는 Isaac Lab 장면 (Scene)을 가지고 있다면, 다음을 수행할 수 있어야 합니다:

1. 이를 적절한 환경 번들 (Environment Bundle)로 패키징하고,
2. EnvHub에 게시(Publish)하며,
3. 깨끗한 머신으로 다시 가져오기(Pull)하고,
4. 암묵적 지식 (Tribal Knowledge) 없이 코드에서 로드하는 것.

그것이 바로 EnvHub를 위한 목적입니다. 내비게이션 (Navigation), 조작 (Manipulation), 휴머노이드 (Humanoid), 보행 (Locomotion), 그리고 당신이 다음에 만들어낼 그 어떤 카테고리에 대해서도 Isaac Lab / Isaac Sim 환경 번들을 위한 카테고리 불문 허브입니다.

이번에는 선언문은 없습니다. 오직 워크플로 (Workflow)뿐입니다.

Nepher에서 "환경 (An environment)"이란 무엇을 의미하는가

CLI를 만지기 전에, 용어를 정확히 이해해야 합니다. 대부분의 재사용 실패는 여기서 시작됩니다.

**환경 (An environment)**은 하나의 _번들 (Bundle)_입니다: 공유된 테마 아래의 하나 이상의 관련 시뮬레이션 장면 (Simulation Scenes)과 메타데이터 (Metadata)의 결합입니다.

각 환경은 다음을 가집니다:

• 고유한 id (예: digital-twin-warehouse-v1)
• 카테고리 (category) (navigation, manipulation, humanoid, locomotion, …)
• 타입 (type): usd 또는 preset
• 버전 (version) 및 설명
• 하나 이상의 장면 (scenes)

**장면 (A scene)**은 실제로 Isaac Lab에 로드하는 구체적인 시뮬레이션 구성입니다. 예를 들어 특정 창고 레이아웃, 병원 복도, 또는 조작 테이블 설정 등이 이에 해당합니다.

실무에서는 두 가지 환경 타입이 중요합니다:

만약 당신의 "환경"이 현재 USD 파일 하나와 반쯤 작성된 README가 들어있는 무작위 폴더 형태라면, 당신은 아직 재사용 가능한 패키지를 가진 것이 아닙니다. 그것은 단지 로컬에서 만든 제작 프로젝트 (craft project)일 뿐입니다. EnvHub의 역할은 그 제작 프로젝트를 주소 지정이 가능한 (addressable) 무언가로 바꾸는 것입니다.

도구 설치 (Install the tools)

EnvHub는 두 가지 방식으로 사용할 수 있습니다:

• nepher — EnvHub에 특화된 패키지 (목록 확인 / 다운로드 / 업로드 / 보기 / Python API)
• npcli — 통합 Nepher CLI (계정, EnvHub, 토너먼트, 해커톤)

이 튜토리얼을 위해 두 가지 모두 설치하십시오. 인증 및 일상적인 EnvHub 명령에는 npcli를 사용하고, Python 로더 (loaders)와 Isaac Sim 보기 도우미 (viewing helpers)가 필요할 때는 nepher를 사용하십시오.

pip install nepher nepher-cli

CLI가 정상 작동하는지 확인합니다:

npcli --version
npcli --help

account.nepher.ai → Account → API Keys에서 API 키를 생성한 다음, 로그인합니다:

npcli login --api-key nepher_xxxxxxxx
npcli whoami

CI (지속적 통합)의 경우, 대화형 로그인을 건너뛰고 다음과 같이 설정하십시오:

export NEPHER_API_KEY=nepher_xxxxxxxx

whoami 명령이 거절 메시지 대신 당신의 계정 정보를 반환하면 준비가 된 것입니다.

1단계 — 이미 존재하는 것 탐색하기 (Discover what already exists)

허브에 이미 존재하는지 확인하기 전까지는 새로운 창고를 제작하지 마십시오.

통합 CLI를 사용하는 경우:

npcli envhub list

EnvHub 패키지를 사용하는 경우 (카테고리 필터 포함):

nepher list --category navigation
nepher list --category manipulation

당신은 다음 세 가지를 확인해야 합니다:

• 충분히 유사한 환경이 이미 존재하는가?
• 카테고리 명명 방식이 당신이 작업을 생각하는 방식과 일치하는가?
• 메타데이터만으로 번들 (bundle)에 무엇이 포함되어 있는지 알 수 있는가?

첫 번째 질문에 대한 답변이 '예'라면, 바로 다운로드 단계로 넘어가세요. 목표가 비교 가능한 연구(comparable research)라면 독창성보다는 재사용성이 더 중요합니다.

2단계 — 깨끗한 머신으로 환경 가져오기 (Pull)

환경 ID(environment id)로 다운로드:

# 통합 CLI (unified CLI)
npcli envhub download <env_id>

...

로컬 캐시(local cache) 확인:

npcli envhub cache list
# 또는
nepher cache list

Isaac Sim을 사용할 수 있다면, 훈련 코드(training code)를 연결하기 전에 장면(scene)을 시각적으로 먼저 열어보세요:

nepher view <env_id> --category navigation
nepher view <env_id> --category navigation --scene hospital

이것이 허브(hub)를 사용하는 이유입니다. 새로운 머신, 새로운 팀원, 새로운 인턴이라 할지라도 — 동일한 명령어로 동일한 세계를 경험할 수 있습니다.

3단계 — Isaac Lab 코드에서 로드하기

EnvHub은 단순한 다운로드 관리자가 아닙니다. nepher 패키지는 번들(bundle)을 연구 코드(research code)로 로드할 수 있는 작은 API를 제공합니다.

from nepher import load_env, load_scene

# 환경 번들(environment bundle) 로드
...

중요한 습관: 환경을 노트북의 절대 경로(absolute paths)가 아닌, id + category + scene으로 참조하세요.

절대 경로는 이동할 수 없지만, 번들 ID(bundle ids)는 이동할 수 있습니다.

4단계 — 자신만의 환경 패키징하기

게시(Publishing)는 manifest.yaml에서 시작됩니다. 그 파일이 바로 계약서입니다.

USD 환경 예시

id: digital-twin-warehouse-v1
type: usd
version: 1.0.0
...

프리셋(Preset) 환경 예시

id: indoor-environments-v1
type: preset
version: 1.0.0
...

후회를 방지하는 패키징 체크리스트

업로드하기 전에 다음 사항을 확인하세요:

1. 안정적인 ID (Stable id) — ID를 패키지 이름처럼 취급하세요. 매주 화요일마다 새로운 ID를 만들어내지 마세요.
2. 정직한 버전 (Honest version) — 장면(scene), 에셋(asset), 또는 작업 의미론(task semantics)이 변경되면 버전을 올리세요.
3. 명확한 설명 (Clear descriptions) — 당신의 Slack 채널에 있지 않았던 낯선 사람을 위해 작성하세요.
4. 상대 경로만 사용 (Relative paths only) — 매니페스트(manifest)가 참조하는 모든 것은 번들(bundle) 내부에 있어야 합니다.
5. 의미 있는 장면 이름 (Scene names that mean something) — scene2보다는 table_clutter_hard가 낫습니다.
6. 썸네일 (Thumbnail) — 단 한 장의 이미지가 다른 사람들이 무엇인지 모른 채 다운로드하는 수고를 덜어줍니다.

유용한 폴더 구조는 다음과 같습니다:

my-env/
  manifest.yaml
  thumbnail.png
...

또는, 프리셋 (presets)의 경우:

my-env/
  manifest.yaml
  thumbnail.png
...

만약 팀원이 매니페스트 (manifest)만 보고 번들 (bundle)을 이해할 수 없다면, 해당 패키지는 완성되지 않은 것입니다.

단계 5 — 업로드 (Upload)

업로드를 위해서는 플랫폼에서의 기여자/평가자 (contributor/evaluator) 권한이 필요합니다. 권한을 얻었다면 다음과 같이 진행합니다:

# 통합 CLI (unified CLI)
npcli envhub upload ./my-env --category navigation

...

그다음 즉시 깨끗한 캐시 (clean cache) 상태에서 해피 패스 (happy path)를 테스트하십시오:

npcli envhub cache clear
npcli envhub download <your_env_id>
nepher view <your_env_id> --category navigation

만약 암묵적인 지식 (tribal memory) 없이 본인의 환경을 직접 가져오고 열 수 없다면, 다른 누구도 할 수 없습니다.

이 단일 루프 — 업로드 (upload) → 캐시 삭제 (wipe cache) → 다운로드 (download) → 보기 (view) — 가 바로 품질 기준입니다.

일반적인 실패 사례 (및 방지 방법)

"내 컴퓨터에서는 잘 되는데" 유형의 경로

하드코딩된 절대 자산 경로 (absolute asset paths)는 번들을 쓸모없게 만드는 가장 빠른 방법입니다. 모든 것을 환경 루트 (environment root) 기준으로 상대 경로로 유지하십시오.

모호한 ID 및 조용한 덮어쓰기

test-env-final-final2는 인프라가 아닙니다. 읽기 쉬운 ID와 실제 버전을 사용하십시오.

장면 혼합 (Scene soup)

서로 관련 없는 12개의 장면 (scenes)이 포함된 하나의 환경은 대개 하나인 척하는 두세 개의 환경일 뿐입니다. 테마별로 그룹화하십시오.

태스크 의미론 (task semantics) 누락

EnvHub는 세상을 패키징합니다. 여러분의 Isaac Lab 태스크 (task) 코드는 여전히 명확한 관측 (observation) / 행동 (action) / 보상 (reward) / 성공 (success) 계약이 필요합니다. 특히 토너먼트 전이라면, 비교 가능한 결과를 위해 이 두 가지를 모두 게시하십시오.

보기 전에 업로드하기

nepher view로 장면을 열어보지 않았다면, 여러분은 희망 사항을 게시하고 있는 것입니다.

이것이 20분의 가치가 있는 이유

개인적인 Isaac Lab 폴더는 한 사람의 학습을 돕습니다.

버전 관리되는 EnvHub 환경은 다음을 돕습니다:

• 다음 팀원이 일주일간의 설정 과정을 건너뛸 수 있게 함,
• 다른 연구실이 동일한 환경을 기준으로 비교할 수 있게 함,
• 토너먼트에서 공정한 평가 팩을 고정할 수 있게 함,
• 미래의 여러분이 "warehouse-v1"이 실제로 무엇을 의미했는지 기억할 수 있게 함.

이것이 바로 시뮬레이션이 일회용 제작물(disposable craft)에서 벗어나 공유 인프라(shared infrastructure)로 변모하는 방식입니다.

첫 번째 문서에서 우리는 중요한 질문은 다음과 같다고 말했습니다: 다른 팀이 우리의 환경을 재현할 수 있는가?

EnvHub는 그 질문에