Docker 빠른 시작

호스트에 Python이나 PyTorch를 설치하지 않고 SDK를 실행합니다. CPU 빠른 시작에는 RAM 8 GB와 여유 디스크 10 GB를 확보하고, Docker Engine 또는 Docker Desktop과 Compose v2 이상이 필요합니다.

저장소 루트에서:

docker compose run --build --rm laya

이것은 체크아웃을 빌드하고, CPU에서 샘플 요청을 실행하며, choice, score, noul을 아우르는 JSON을 출력합니다. 첫 요청은 선택된 공개 Hugging Face 체크포인트를 내려받으며, 계정은 필요하지 않습니다. 첫 다운로드에는 몇 분을 허용하십시오. 가중치는 명명된 볼륨에 남습니다. 이후 실행은 docker compose run --rm laya를 씁니다.

예측과 신뢰도는 여전히 당신의 워크로드에서 평가가 필요합니다. 벤치마크 한계를 참고하십시오.

ARM64 호스트, DGX Spark, Apple Silicon은 ARM64와 DGX Spark 컨테이너를 참고하십시오.

NVIDIA GPU / CUDA

호환되는 NVIDIA 드라이버를 설치하고 NVIDIA Container Toolkit으로 Docker를 설정하십시오. GPU 이미지는 PyTorch CUDA 12.8 휠을 사용합니다. GPU의 컴퓨트 능력과 드라이버를 PyTorch가 지원하는 빌드와 대조해 확인하십시오. 오래된 카드는 다른 빌드가 필요할 수 있습니다. CUDA 계층을 위한 추가 디스크 공간을 확보하십시오. VRAM 요구량은 체크포인트, 배치 크기, 입력 길이에 달려 있습니다.

docker compose -f compose.yaml -f compose.cuda.yaml run --build --rm laya

오버라이드는 GPU 0을 선택하고 기본값은 LAYA_DEVICE=cuda입니다. LAYA_GPU_ID를 다른 호스트 인덱스나 UUID로 설정하십시오. 그 GPU는 컨테이너 안에서 장치 0으로 나타납니다. 가중치를 내려받지 않고 접근을 확인하십시오:

docker compose -f compose.yaml -f compose.cuda.yaml run --rm laya python -c \
  'import torch; assert torch.cuda.is_available(); print(torch.cuda.get_device_name(0)); print(torch.ones(1, device="cuda").cpu())'

샘플은 체크포인트를 로드하기 전에 사용할 수 없는 CUDA를 거부합니다. Laya는 메모리나 추론 오류 후에도 여전히 CPU로 폴백할 수 있으므로, 경고를 살펴보십시오. CPU와 CUDA 구성 사이를 전환할 때는 다시 빌드하십시오.

이미지는 TORCH_DISABLE_NATIVE_JIT=1을 설정합니다. 그렇지 않으면 PyTorch 2.14가 일부 eager CUDA 연산을 첫 추론 시 컴파일하는 Triton 커널로 대체하는데, 여기에는 슬림 이미지가 갖추지 못한 C 컴파일러가 필요합니다. 컨테이너는 정상이라고 보고한 뒤 모든 요청을 실패시킵니다(#365). 기본 커널은 같은 지연 시간에 같은 답을 줍니다. 베어메탈 설치에서 predict가 Failed to find C compiler로 실패하면 같은 변수를 설정하십시오.

이것은 Compose GPU 예약을 사용합니다. Windows는 Docker Desktop이 지원하는 WSL2 GPU 설정이 필요합니다. Apple MPS, AMD/ROCm, Intel GPU 컨테이너는 이 빠른 시작의 범위 밖입니다. 다른 백엔드를 설정하고 검증하지 않는 한 CPU를 쓰십시오.

설정

Compose 변수는 셸, 로컬 .env 파일, 또는 서비스의 environment 블록에서 설정하십시오. .env에 비밀을 커밋하지 마십시오. 런타임 변수는 docker run -e로도 동작하며, Compose 전용 설정은 아래에서 표시합니다.

Compose는 HF_HOME을 제외한 런타임 변수를 전달합니다. HF_HOME은 고정된 캐시 마운트와 정렬된 상태로 유지됩니다. 또한 MPS 행 게이트인 LAYA_MPS_AMP_MIN_ROWS도 제외되는데, 여기 어떤 컨테이너도 MPS를 선택할 수 없으므로 여기 어떤 이미지도 그것에 도달할 수 없습니다. docker run이나 자체 Compose 파일에서 HF_HOME을 오버라이드한다면, UID 10001이 쓸 수 있는 일치하는 마운트를 제공하십시오. 직접 Docker 빌드는 --build-arg TORCH_INDEX=cu128로 PyTorch를 선택하며, 런타임 -e는 설치된 휠을 바꿀 수 없습니다.

LAYA_MODEL=english OMP_NUM_THREADS=2 docker compose run --build --rm laya

docker build -t laya:local .
docker run --rm -e LAYA_MODEL=english -e OMP_NUM_THREADS=2 \
  -v laya-model-cache:/home/laya/.cache/huggingface laya:local

직접 만든 요청에는:

docker compose run --rm --volume "$PWD/request.json:/inputs/request.json:ro" \
  --env LAYA_REQUEST_FILE=/inputs/request.json laya

요청, 체크포인트, 비밀 파일 마운트가 있는 주석 달린 구성은 compose.example.yml을 참고하십시오:

docker compose -f compose.yaml -f compose.example.yml run --build --rm laya

NVIDIA GPU라면 run 앞에 -f compose.cuda.yaml을 추가하십시오. 이 예제는 compose.yaml의 오버라이드이므로, 캐시와 이미지 설정이 한곳에 유지됩니다.

비밀 파일

HF_TOKEN_FILE은 시작 시 마운트된 UTF-8 파일을 읽고, 주변 공백을 다듬으며, HF_TOKEN보다 우선합니다. 읽을 수 없거나 비어 있거나 유효하지 않은 파일은 내용을 출력하지 않고 시작을 중단합니다. 파일은 UID 10001이 읽을 수 있어야 합니다. _FILE은 지원되는 비밀에만 적용되지, 모든 설정에 적용되지는 않습니다.

HF_TOKEN_PATH가 체크아웃 밖의 기존 호스트 파일을 가리킬 때:

docker compose run --rm --volume "$HF_TOKEN_PATH:/run/secrets/hf_token:ro" \
  --env HF_TOKEN_FILE=/run/secrets/hf_token laya

Docker 시크릿이나 Kubernetes Secret 볼륨도 같은 파일을 공급할 수 있습니다. 값은 시작 시 프로세스 환경으로 로드되므로, 파일을 바꾼 뒤 재시작하십시오. 토큰을 빌드 인수로 쓰거나 이미지에 굽지 마십시오. 공개 체크포인트에는 토큰이 필요하지 않습니다.

파인튜닝된 체크포인트

이 이미지는 추론을 실행합니다. 파인튜닝은 그 밖에서 일어납니다. 파인튜닝 노트북이 Kaggle의 무료 2xT4 GPU에서 전체 루프를 실행하고, 이 이미지가 서빙할 수 있는 체크포인트를 익스포트합니다. 학습 인터페이스에 관한 배경과 미해결 질문은 #4와 #26에 남아 있습니다.

LAYA_CHECKPOINT_PATH를 rl_agent_config.json, model.safetensors 및 일치하는 토크나이저 파일을 담은 절대 호스트 디렉터리로 향하게 하십시오:

docker compose run --rm --volume "$LAYA_CHECKPOINT_PATH:/models/custom" \
  --env LAYA_MODEL_PATH=/models/custom laya

로더가 토크나이저 설정을 갱신할 수 있으므로 UID 10001이 쓸 수 있는 작업 사본을 쓰십시오. LoRA 어댑터만으로는 완전한 체크포인트가 아닙니다. LAYA_MODEL_PATH를 설정할 때는 LAYA_MODEL=auto로 두십시오. 명시적 별칭과 로컬 경로는 상호 배타적입니다. 로컬 경로 응답은 Agent에서 오며 Router routing 메타데이터가 없습니다. 이 설정들은 CUDA 오버라이드와도 동작합니다. 파인튜닝된 체크포인트는 의존하기 전에 홀드아웃 예제로 평가하십시오.

ModelScope에서 받는 모델

호스트가 huggingface.co에 접근할 수 없을 때는 체크포인트를 ModelScope에서 받아 빌드 시점에 이미지에 구워 넣을 수 있습니다. 어떤 체크포인트를 고를지는 인수 하나로 정하며 기본값은 다국어판입니다. Compose 오버라이드는 프리페치 인수를 두 서비스 모두에 추가하고 컨테이너를 Hub에서 떼어 놓습니다:

docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve

NVIDIA라면 up 앞에 -f compose.cuda.yaml을 추가하십시오. 이 override는 두 서비스 모두에 대해 자기 인수를 반복하므로 두 override의 순서는 상관없습니다. 순수 Docker는 인수를 직접 받습니다:

docker build --build-arg MODELSCOPE_MODEL=multilingual \
  -t laya:local .
docker run --rm -e HF_HUB_OFFLINE=1 -p 127.0.0.1:8000:8000 laya:local laya-serve

이전에 이것을 실행한 적 있는 호스트에는 전제가 하나 있습니다. 구워 넣은 가중치는 이미지 안 $HF_HOME/hub, 즉 compose.yaml이 model-cache 볼륨을 마운트하는 캐시 디렉터리 (/home/laya/.cache/huggingface) 아래에 놓이고, Docker가 이름 있는 볼륨을 이미지에서 시드하는 것은 그 볼륨이 비어 있을 때뿐입니다. Hub 기반 빠른 시작에서 남은 볼륨은 오래된 Hub 스냅샷을 담고 있고 다시 시드되지 않으며, 구워 넣은 가중치는 그 뒤에서 보이지 않는 채로 남습니다: 로더가 refs/main을 오래된 Hub 커밋으로 해석하고 컨테이너는 이미 내려받은 가중치로 답합니다. 마치 재빌드가 아무것도 바꾸지 않은 것처럼. 배포를 빈 캐시 볼륨으로 향하게 하십시오 —— 같은 Compose 파일과 같은 LAYA_CACHE_VOLUME으로 docker compose down --volumes를 실행하거나, 새 볼륨에는 LAYA_CACHE_VOLUME=<name>을 씁니다. HF_HUB_OFFLINE=1에서는 없거나 어긋난 ref가 폴백할 네트워크 없는 로드 실패가 되지만, 전제는 같습니다.

docker/prefetch_modelscope.py 는 modelscope.cn의 저장소를 나열하고, 체크포인트 자체의 파일 —— laya/agent.py가 Hub에 요청하는 것과 같은 집합이라 형제 체크포인트는 당겨오지 않습니다 —— 을 내려받아, snapshot_download가 스냅샷을 배치하는 방식 그대로 이미지의 hub 캐시에 씁니다. 그 밖에는 아무것도 바뀌지 않습니다: Agent, laya-serve가 만드는 Router, laya.cli, 그리고 각 통합은 자기 repo id를 유지하고 그것을 구워 넣은 스냅샷으로 해석하므로, 이렇게 빌드한 컨테이너는 네트워크가 전혀 필요 없습니다. 각 파일의 크기는 스냅샷이 게시되기 전에 저장소가 보고하는 값과 대조되고, 저장소가 게시하면 SHA-256도 함께 대조됩니다. 크기나 다이제스트가 어긋나면 빌드가 실패합니다. 다이제스트를 게시하지 않는 저장소는 크기만 검사하게 되고, 이는 같은 크기의 바꿔치기를 잡아내지 못합니다.

타입은 번들 저장소 안에서 그 체크포인트의 경로로 펼쳐지고, 이는 Router와 일회성 빠른 시작이 기본으로 로드하는 것이므로, 타입 하나를 지정한 빌드는 더 이상 바꾸지 않고도 그것을 제공합니다:

MODELSCOPE_MODEL=english docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve
MODELSCOPE_MODEL=all docker compose -f compose.yaml -f compose.http.yaml -f compose.modelscope.yaml up --build laya-serve

all은 온 가족으로 약 2.4 GB의 가중치입니다. 이 override는 LAYA_MODELS=multilingual도 설정합니다. 기본 목록으로 LAYA_PRELOAD=1을 쓰면 모든 체크포인트를 만들려다 구워 넣지 않은 첫 번째에서 실패하기 때문입니다. 더 구워 넣을 때는 LAYA_MODELS를 구워 넣은 목록으로 설정하고, 배포가 정말 온 가족을 제공할 때는 MODELSCOPE_MODEL=all을 설정하십시오.

여러 타입을 한 번에 지정할 수 있습니다 —— MODELSCOPE_MODEL="english multilingual"은 둘 다 구워 넣으며 약 1.5 GB입니다 —— 보통 제공 이미지가 원하는 것이 바로 이것입니다: Router가 영어와 다국어 체크포인트를 스스로 고르고, 주지 않은 것은 로그의 does not contain 'rl_agent_config.json'와 함께 500 inference failed로 답합니다. 저장소를 공유하는 체크포인트는 항상 하나의 스냅샷으로 구워집니다. 캐시된 리비전은 단일 디렉터리로 해석되므로 루트 체크포인트와 각 하위 폴더가 모두 그 안에 들어갑니다.

타입뿐 아니라 이 인수는 repo[:subfolder] 형식 지정도 받습니다. 쉼표나 공백으로 구분하며, 미러의 독립 저장소 (laya, laya-multilingual, laya-typed-decisions)나 파인튜닝된 체크포인트를 구워 넣는 방식이 이것입니다. 독립 저장소는 Agent("convaiinnovations/laya-multilingual")가 직접 로드하는 것입니다. Router의 기본은 번들 경로이므로, 제공 이미지가 보통 원하는 것은 타입입니다.

핀과 출처에 관한 두 가지 세부 사항. 빌드는 스냅샷이 키로 삼는 커밋, 즉 구워 넣은 리비전의 끝을 출력합니다 —— 그 SHA를 revision= 또는 LAYA_REVISION으로 넘기면 로드를 구워 넣은 그대로에 정확히 고정할 수 있습니다. 미러 저장소는 여러 업로드의 파일을 담을 수 있으므로 그 끝이 유일하게 존재하는 저장소 차원의 키입니다. Hub 쪽 핀은 미러 스냅샷을 설명하지 않습니다: reviewed는 Hugging Face 커밋을 가리키고, SHA-256 다이제스트 맵은 Hub 아티팩트 해시를 키로 삼으므로 둘 다 여기에는 해당하지 않으며, 미러 스냅샷에는 다이제스트 핀도 없습니다. 빌드는 이미 미러가 보고한 크기와 맞지 않는 다운로드를 거부합니다 —— 미러가 게시하면 다이제스트도 마찬가지입니다 —— 다만 이것은 미러 메타데이터와의 일관성을 검사하는 것이지 독립적으로 고정된 다이제스트가 아닙니다. 가중치는 인수가 지정한 미러 계정에서 오므로, 그것은 배포가 스스로 내려야 할 공급망 결정입니다.

개발과 정리

docker compose run --rm laya python으로 Python 프롬프트를 여십시오. 가중치를 내려받지 않고 체크아웃에 대해 기존 라우팅/criteria 검사와 비밀 파일 테스트를 실행하려면:

docker compose run --rm --volume "$PWD:/workspace:ro" --workdir /workspace laya \
  sh -ec 'python tests/test_router.py; python tests/test_criteria.py; python tests/test_docker_entrypoint.py'

소스나 번들 예제를 바꾼 뒤에는 --build로 다시 빌드하십시오. 이미지는 UID/GID 10001로 실행됩니다. 새 명명 볼륨은 이미지 캐시 디렉터리의 소유권을 상속하고, 호스트 디렉터리는 그 UID가 쓸 수 있어야 합니다. 토크나이저 호환성 갱신을 위해 모델 캐시를 쓰기 가능하게 유지하십시오.

--rm은 완료된 컨테이너를 제거합니다. docker compose down은 캐시를 유지합니다. 내려받은 가중치를 삭제하려면 같은 Compose 파일과 LAYA_CACHE_VOLUME 설정으로 docker compose down --volumes를 실행하십시오. 다음 요청이 그것들을 다시 내려받습니다. 다른 프로젝트와 공유하는 캐시는 제거하지 마십시오.

HTTP 서빙

이미지는 laya-serve를 포함하므로, 일회성 빠른 시작을 실행하는 같은 빌드가 Jev 호환 API를 서빙할 수 있습니다. compose.http.yaml은 그것을 두 번째 서비스로 추가하고 laya는 그대로 둡니다:

docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve
curl -s localhost:8000/health
curl -s localhost:8000/v1/systemone -H 'content-type: application/json' \
  --data @examples/docker/request.json

NVIDIA라면 CUDA 오버라이드를 추가하십시오. laya-serve는 별개 서비스이고 laya에 대한 오버라이드는 결코 그것에 도달하지 않으므로, laya-serve를 위해 빌드 인수와 장치 예약을 반복합니다:

docker compose -f compose.yaml -f compose.http.yaml -f compose.cuda.yaml up --build laya-serve

up은 서비스를 포그라운드에서 계속 실행하고, -d는 분리합니다. 가중치는 빠른 시작과 같은 명명 model-cache 볼륨으로 가므로, 빠른 시작 실행 후 서빙하면 체크포인트가 이미 디스크에 있는 상태로 시작합니다. 같은 Compose 파일을 써서 docker compose ... down으로 중지하십시오.

포트는 127.0.0.1에만 게시됩니다. LAYA_API_KEY를 설정하기 전까지 API에는 인증이 없으므로, LAYA_BIND_ADDRESS=0.0.0.0으로 노출하기 전에 키를 설정하고, 원격 클라이언트를 위해 TLS 리버스 프록시를 앞에 두십시오. 어느 경우든 /health는 인증을 요구하지 않으므로 아래 헬스체크는 계속 동작합니다. 키를 설정하면 인증되지 않은 호출자에게 {"status": "ok"}라고 답하고, bearer가 필요한 checkpoint, revision, device 필드는 감춥니다.

서비스에는 /health에 대한 헬스체크가 있습니다. 서버는 리스닝을 시작하기 전에 미리 로드하므로, LAYA_PRELOAD=1이면 정상 컨테이너는 체크포인트가 로드된 상태입니다. docker compose ... up -d --wait laya-serve는 정상이 되면 반환합니다.

/health는 device를 상주 체크포인트가 실제로 계산하는 장치로 보고하며, 이는 항상 LAYA_DEVICE가 요청한 것과 같지는 않습니다. 얻을 수 없는 GPU를 원하는 체크포인트는 조용히 CPU로 폴백하고도 여전히 올바르게 답합니다. checkpoint_devices는 로드된 각 체크포인트의 이름을 밝히고, device_is_preference는 아무것도 상주하지 않을 때만 true이므로, 조용히 GPU를 잃은 배포는 자기 구성을 되돌려 읊는 대신 그렇게 말합니다.

서버 설정

이것들은 laya-serve 서비스에만 적용됩니다.

예를 들어 API를 /laya 아래에 게시할 때는 LAYA_ROOT_PATH=/laya를 설정하십시오. 프록시는 컨테이너로 전달하기 전에 그 접두사를 제거해야 합니다. 이 설정은 FastAPI가 생성하는 URL을 갱신하며 내부 /health나 /v1/systemone 라우트를 바꾸지는 않습니다.

여기서 LAYA_PRELOAD는 패키지 기본값 1이 아니라 0입니다. 미리 로드하면 첫 부팅이 세 체크포인트를 모두 내려받기 때문입니다. 오래 실행되는 배포라면 첫 요청이 빌드 비용을 치르지 않도록 1로 설정하십시오.

LAYA_PORT는 게시된 호스트 포트와 서버가 바인드하는 포트를 모두 설정하므로 둘이 어긋날 수 없습니다. 서비스를 옮기려면 한 곳만 바꾸십시오:

LAYA_PORT=9000 docker compose -f compose.yaml -f compose.http.yaml up --build laya-serve

파일에서 오는 Bearer 토큰

LAYA_API_KEY_FILE은 시작 시 한 번 읽히고, LAYA_API_KEY로 옮겨지며, 서버가 exec되기 전에 _FILE 변수가 제거됩니다. 키를 환경에 두는 것보다 이것을 선호하십시오:

docker compose -f compose.yaml -f compose.http.yaml run --rm \
  --volume "$PWD/laya_api_key:/run/secrets/laya_api_key:ro" \
  -e LAYA_API_KEY_FILE=/run/secrets/laya_api_key \
  --service-ports laya-serve