JupyterLab 작업공간과 앱

JupyterLab 작업공간은 데이터셋과 테이블 읽기/쓰기, 원본 파일 입출력, Python 패키지 설치와 온톨로지 사용을 지원합니다. Dash 및 Streamlit 앱을 게시할 수 있으며 TensorBoard는 미리보기만 지원합니다.

시작과 저장, 데이터 접근, 온톨로지와 모델의 권한 및 별칭 조건을 함께 사용합니다.

편집기 설정

Settings에서 정한 JupyterLab 환경설정은 다른 Jupyter 작업공간에도 유지됩니다. 입력 중 코드 완성을 제안하는 Continuous hinting은 기본으로 켜져 있습니다.

Applications 패널

왼쪽 Applications는 앱 유형 하나씩 표시합니다. 위쪽 Application type의 드롭다운에서 Dash, Streamlit 또는 TensorBoard를 선택하면 해당 유형의 앱과 동작을 보여 주며 작업공간별 선택을 기억합니다.

관리형 Conda/PyPI 환경에서는 Dash 또는 Streamlit을 게시하기 전에 해당 앱 라이브러리를 Conda로 설치해야 합니다. 예를 들어 Streamlit 게시에는 streamlit이 필요합니다. 없으면 Publish application을 비활성화하고 필요한 패키지를 표시합니다. 같은 라이브러리를 PyPI로만 설치한 상태는 이 게시 조건을 충족하지 않습니다.

maestro env conda install dash streamlit

TensorBoard의 라이브러리 안내는 게시 흐름이 없는 미리보기용 정보이며 Open preview 자체는 계속 사용할 수 있습니다. 실제 미리보기 서버를 실행할 패키지는 환경에 있어야 합니다.

Dash 게시와 미리보기

1. Application type을 Dash로 선택합니다.
2. Publish application에서 저장할 Files and Projects 위치를 정합니다.
3. 저장소 루트 기준의 모듈 이름과 서버 변수 이름을 입력합니다. 모듈 이름 app은 app.py, folder.app은 folder/app.py에 대응합니다. 서버 변수는 보통 server입니다.
4. 필요하면 Advanced 설정을 바꿉니다. 기본으로 작업공간 설정을 사용합니다.
5. Publish and sync로 앱을 등록하고 코드를 동기화합니다. CI 및 게시가 끝나면 Applications의 링크로 엽니다.

지정한 모듈 경로에 파일을 자동 생성합니다. 모듈 이름은 점으로 구분한 Python 경로이며 파일 확장자를 붙인 경로와 구분합니다.

대화형 개발에서는 작업공간 터미널에서 실제 파일을 실행한 뒤 Applications > Dash > Open preview를 선택합니다.

python app.py

게시한 Dash는 앱 Python 파일 실행 후 30초 안에 서버가 시작되어야 합니다. 오래 걸리는 초기화나 설치를 앱 시작에 포함하면 시작 실패가 발생할 수 있습니다.

Streamlit 게시와 미리보기

1. Application type을 Streamlit으로 선택합니다.
2. Publish application에서 위치를 정하고 저장소 루트 기준 Python 파일 이름을 입력합니다. 예: app.py.
3. 필요하면 Advanced 설정을 바꿉니다.
4. Publish and sync를 선택하고 CI 및 게시 완료 후 앱 링크를 엽니다.

대화형 미리보기에서는 파일을 Streamlit으로 실행합니다.

streamlit run app.py

Applications > Streamlit > Open preview를 선택합니다. 게시한 Streamlit도 Python 파일 실행 후 30초 안에 서버가 시작되어야 합니다.

브랜치와 제한 뷰 입력

작업공간의 새 브랜치에서 앱을 게시하거나 코드를 동기화하면 그 브랜치의 새 앱 버전을 만듭니다. 사용자에게 제공하기 전에 그 버전을 확인하고 master에 반영하려면 브랜치를 master로 병합합니다.

Dash와 Streamlit은 제한 뷰를 입력으로 사용할 수 있습니다. 먼저 Restricted outputs mode를 켭니다. 이 앱 경로에서는 게시한 앱을 여는 사용자마다 자신의 권한으로 허용된 데이터만 봅니다. 제한 뷰에서 파생한 데이터셋, 모델 또는 테이블 출력을 게시하는 것과는 구분합니다.

TensorBoard 미리보기

TensorFlow 로그가 있는 실제 디렉터리를 LOG_DIRECTORY로 제공하고 작업공간 터미널에서 실행합니다.

: "${LOG_DIRECTORY:?LOG_DIRECTORY is required}"
tensorboard --logdir="$LOG_DIRECTORY"

Applications > TensorBoard > Open preview를 선택합니다. TensorBoard는 앱 게시 대상이 아닙니다.

AIP 코딩 에이전트

AIP를 활성화한 플랫폼 인스턴스에서는 Experimental AIP 에이전트를 사용할 수 있습니다. 왼쪽 아래 </> 아이콘을 선택하고 Ask a question... 입력란에 요청합니다. 지원 LLM을 사용해 설명하거나 사용 가능한 도구로 파일과 코드를 작성합니다.

렌치 아이콘에서 Tools를 확인하고 필요 없는 도구를 끌 수 있습니다. 도구는 파일 작성, 코드 작성/실행, 라이브러리 검색/설치와 터미널 명령을 지원합니다. 세션 권한과 도구의 접근 범위를 함께 확인합니다.

Settings 메뉴에서는 대화 thread 이름을 바꾸고 system prompt를 볼 수 있습니다. 입력란 아래 모델 이름으로 LLM을 변경할 수 있으며 제공자별 동작이 다를 수 있습니다.

채팅 이력은 작업공간 종료나 재시작 뒤 유지되지 않습니다. 남겨야 할 코드와 모델 출력은 세션을 끝내기 전에 적절한 저장/게시 경로로 보존합니다. 에이전트는 분석, 시각화와 모델링 코드, 코드 설명, 반복 설치/정리 작업 및 Dash/Streamlit 앱 개발에 사용할 수 있습니다.

Notebook을 transform으로 게시

Jupyter notebook transform은 외부 서비스 API 호출을 지원하지 않습니다. 작업공간의 대화형 소스 연결을 transform의 외부 연결로 그대로 사용할 수 없습니다. 재현 가능한 외부 호출 파이프라인에는 외부 transform 경로를 사용합니다.

1. 실행할 notebook을 작업공간 파일로 저장합니다.
2. Data의 출력 데이터셋 옆 파란 Build 아이콘을 선택합니다.

3. 추론한 notebook, 입력과 출력을 확인합니다. 잘못 추론한 항목은 직접 바꾸고 CPU/메모리를 정합니다.

4. Sync and run으로 설정을 저장하고 CI를 실행하여 출력 데이터셋의 transform 및 JobSpecs를 게시합니다. CI가 완료되면 데이터 파이프라인의 빌드와 스케줄 등으로 관리합니다.

환경 동작은 관리형 환경을 사용하는지에 따라 다릅니다. 활성화했다면 아래 manifest/lock으로 실행 환경을 복원합니다. 관리형 환경을 사용하지 않는 기존 notebook transform은 필요한 의존성을 notebook의 설치 셀에 명시해야 합니다. 다음은 직접 mamba를 사용하는 Deprecated 경로의 notebook 셀 예입니다.

!mamba install -y -q scikit-learn scikit-image

새 관리형 환경에서는 반복 설치 셀 대신 Maestro로 의존성을 관리합니다.

관리형 Conda/PyPI 환경

Maestro는 설치 요청과 해결된 의존성을 저장소 파일로 추적합니다.

hawk.lock은 Deprecated conda.lock을 대체합니다. lockfile은 직접 수정하지 않고 설치 명령으로 갱신합니다. manifest도 Git 충돌 해결 같은 경우 외에는 명령이 관리하도록 둡니다.

관리형 환경은 작업공간 시작, 게시한 앱 시작, notebook transform 실행과 모델 실행 전에 복원됩니다.

활성화

Settings > Advanced features에서 Managed Conda environments를 켜고 작업공간을 재시작합니다.

이후 default 관리형 환경을 선택할 수 있습니다.

설치와 제거

Libraries에서 검색하여 설치하거나 작업공간 터미널의 Maestro를 사용합니다. Libraries의 설치 명령도 notebook 셀이나 앱 코드가 아닌 새 터미널에서 실행합니다.

다음 명령은 LIBRARY_NAME에 실제 패키지 이름을 제공한 경우입니다. Conda와 PyPI 중 해당 패키지를 관리할 경로를 선택합니다.

: "${LIBRARY_NAME:?LIBRARY_NAME is required}"
maestro env conda install "$LIBRARY_NAME"

: "${LIBRARY_NAME:?LIBRARY_NAME is required}"
maestro env pip install "$LIBRARY_NAME"

버전을 지정할 때는 LIBRARY_VERSION을 함께 제공합니다.

: "${LIBRARY_NAME:?LIBRARY_NAME is required}"
: "${LIBRARY_VERSION:?LIBRARY_VERSION is required}"
maestro env conda install "${LIBRARY_NAME}==${LIBRARY_VERSION}"

PyPI도 maestro env pip install "${LIBRARY_NAME}==${LIBRARY_VERSION}" 형식입니다. 제거는 관리한 패키지 출처에 맞는 옵션을 선택합니다.

maestro env uninstall --conda-dependencies "$LIBRARY_NAME"

maestro env uninstall --pip-dependencies "$LIBRARY_NAME"

설치 명령을 실행하면 meta.yaml에는 요청이, hawk.lock에는 현재 해결된 환경이 반영됩니다. 설치 목록은 Libraries에서 볼 수 있습니다.

파일 확인과 브랜치 변경

View > Show Hidden Files를 켠 뒤 .envs/maestro에서 manifest와 lockfile을 봅니다.

브랜치를 바꾸거나 Git 변경을 가져와 lockfile 내용이 달라졌으면 작업공간 터미널에서 실행합니다.

maestro env install

이 명령은 manifest에서 lockfile을 다시 해결하고 default 환경에 설치합니다.

충돌과 업그레이드

Git 충돌이 생기면 생성물인 hawk.lock을 제거하고 meta.yaml의 요청 제약을 해결한 뒤 브랜치를 병합합니다. 이후 maestro env install로 lockfile을 다시 만들고 환경을 설치합니다.

환경 전체를 새 버전으로 해결하려면 필요한 작업과 의존성 설정을 먼저 저장한 뒤 hawk.lock과 설치 환경을 제거합니다. 다음 명령은 Code Workspace의 고정된 환경 경로를 삭제하므로 실행 대상과 저장 상태를 확인해야 합니다.

rm /home/user/repo/.envs/maestro/hawk.lock &&
rm -rf /home/user/envs/default &&
maestro env install

제약 안에서 의존성을 새로 해결하고 설치하므로 업그레이드 결과는 기존 lockfile과 달라질 수 있습니다.

manifest와 lockfile 형식

meta.yaml은 Conda 메타데이터 형식을 사용하며 Jupyter 관리 환경에는 requirements.run과 requirements.pip의 요청을 사용합니다.

package:
  name: '{{ PACKAGE_NAME }}'
  version: '{{ PACKAGE_VERSION }}'
requirements:
  build: []
  run:
    - ipykernel
    - pip
    - foundry-transforms-lib-python
    - pandas
    - polars
    - dash
    - streamlit
    - tensorboard
  pip:
    - Flask-Testing
  run_constrained: []
source:
  path: ../src
build: null
test: null
about: null

package의 값은 템플릿 변수이며 일반 Conda 필드와 실제로 읽는 requirements 두 항목을 구분합니다.

hawk.lock은 전체 예시 파일에서 볼 수 있습니다. 이 파일은 형식을 설명하는 예이며 현재 환경을 그 파일로 덮어쓰지 않습니다.

• conda 구역은 패키지, 버전, 빌드 및 채널 식별자를 기록합니다.
• pip 구역은 PyPI 버전 선택을 기록합니다.
• conda-metadata는 채널 식별자를 플랫폼, 패키지 형식과 저장소에 연결합니다.
• conda lock version은 lock 형식 및 식별 정보를 기록합니다.

실제 환경에는 해당 작업공간에서 Maestro가 생성한 파일을 사용합니다.