Skip to content

ENV_SETUP.md

Latest commit

 

History

History
246 lines (172 loc) · 5.74 KB

ENV_SETUP.md

File metadata and controls

246 lines (172 loc) · 5.74 KB

SAM3DServer Environment Setup Guide

This guide covers end-to-end environment setup for the current architecture in this repository. The setup below does not rely on VIGA at runtime.

Scope:

  • Includes SAM + SAM3D
  • Excludes SAM3 and infinigen

Runtime architecture:

  • Process 1: public API (sam3d_server.main_service, port 8004)
  • Process 2: internal SAM service (sam3d_server.sam_service, port 9001)
  • Process 3: internal SAM3D service (sam3d_server.sam3d_service, port 9002)

1. Prerequisites

  1. Linux + NVIDIA GPU (SAM3D requires high VRAM).
  2. NVIDIA driver available (nvidia-smi should work).
  3. git with submodule support.
  4. conda (Miniconda/Anaconda) for local run.
  5. curl available in shell.
  6. Optional but recommended: Docker + NVIDIA Container Toolkit.

Check GPU:

nvidia-smi

2. Clone and Init Submodules

From project root (/Users/fishwowater/projects/SAM3DServer):

git submodule update --init --recursive third_party/sam third_party/sam3d

3. Local Conda Environments

Create two environments:

conda create -n sam python=3.10 -y
conda create -n sam3d-objects python=3.11 -y

Install dependencies:

conda run -n sam --no-capture-output \
  pip install -r requirements/requirement_sam.txt

conda run -n sam3d-objects --no-capture-output \
  pip install -r requirements/requirement_sam3d-objects.txt

conda run -n sam3d-objects --no-capture-output \
  pip install 'huggingface-hub[cli]<1.0'

For SAM3D-specific pinned CUDA/PyTorch and third-party build dependencies (without model download), use:

bash scripts/setup_sam3d_env.sh

4. Model Download Configuration

Set token for SAM3D checkpoint download (first run only):

export HF_TOKEN="<your_huggingface_token>"

Notes:

  • SAM checkpoint is public and downloaded automatically.
  • SAM3D checkpoint is from Hugging Face model facebook/sam-3d-objects.
  • If SAM3D checkpoints already exist locally, HF_TOKEN is not required.

Default model location for local run:

<repo>/models

You can override:

export MODEL_ROOT="/your/custom/models/path"

5. Start the Services (Local)

From repo root:

bash scripts/start_sam_http.sh start

What this script does:

  1. Ensures model files exist (scripts/ensure_models.sh).
  2. Starts internal SAM service on 127.0.0.1:9001.
  3. Starts internal SAM3D service on 127.0.0.1:9002.
  4. Starts public API on 0.0.0.0:8004.

Port environment variables (optional, defaults shown):

export SAM_INTERNAL_PORT=9001
export SAM3D_INTERNAL_PORT=9002
export SAM_HTTP_PORT=8004

Service management commands:

bash scripts/start_sam_http.sh status
bash scripts/start_sam_http.sh stop
bash scripts/start_sam_http.sh restart

Optional startup timeout tuning:

export HEALTH_WAIT_SECONDS=600
bash scripts/start_sam_http.sh start

6. Verify Service Health

In another terminal:

curl -s http://127.0.0.1:8004/healthz | python -m json.tool

Expected key fields:

  • sam_service: true
  • sam3d_service: true
  • status: "ok" (or "degraded" if one internal service is unavailable)

7. Run Python Client Examples

Put two test images under assets/:

  • assets/image1.jpg
  • assets/image2.jpg

Run examples:

python examples/client_segment_image.py
python examples/client_reconstruct_scene.py

Artifacts are downloaded to:

output/<job_id>/

8. Docker Deployment (Compose Pull + Up)

Recommended:

export HF_TOKEN="<your_huggingface_token>"
bash scripts/docker_compose_up.sh up

Equivalent raw compose commands:

docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d

Notes:

  • Default image is fishwowater/sam3dserver:latest.
  • Compose exposes ports 9001/9002/8004 (SAM/SAM3D/public API).
  • Models persist in compose volume sam_models.

Health check after startup:

curl -s http://127.0.0.1:8004/healthz | python -m json.tool

9. Common Errors and Fixes

  1. HF_TOKEN is not set
  • Cause: SAM3D checkpoint missing and token not provided.
  • Fix: export HF_TOKEN=... and restart.
  1. SAM checkpoint not found
  • Cause: model download failed or path mismatch.
  • Fix: check MODEL_ROOT and SAM_CHECKPOINT, rerun startup script.
  1. SAM3D config not found
  • Cause: SAM3D checkpoints missing or wrong SAM3D_CONFIG_PATH.
  • Fix: confirm <MODEL_ROOT>/sam3d/checkpoints/hf/pipeline.yaml exists.
  1. /healthz returns degraded
  • Cause: internal SAM or SAM3D service failed to load.
  • Fix: inspect startup logs for 9001 / 9002 loading errors.
  1. OOM during reconstruction
  • Cause: insufficient VRAM for SAM3D model/inference.
  • Fix: reduce concurrent external traffic (queue is serial), use larger GPU, or lower workload size.

10. Environment Variables Reference

Main variables used by this project:

  • HF_TOKEN: Hugging Face token for SAM3D checkpoint download.
  • MODEL_ROOT: root directory for model files.
  • SAM_CHECKPOINT: SAM checkpoint path.
  • SAM3D_CONFIG_PATH: SAM3D pipeline config path.
  • SAM_INTERNAL_PORT: startup script SAM service port (default 9001).
  • SAM3D_INTERNAL_PORT: startup script SAM3D service port (default 9002).
  • SAM_HTTP_PORT: startup script public API port (default 8004).
  • SAM_INTERNAL_BASE_URL: internal SAM service URL (default http://127.0.0.1:9001).
  • SAM3D_INTERNAL_BASE_URL: internal SAM3D service URL (default http://127.0.0.1:9002).
  • SAM_HTTP_BASE_URL: public API base URL (default http://127.0.0.1:8004).
  • SAM_HTTP_JOB_ROOT: job output directory (default /var/lib/sam-http/jobs).
  • SAM_HTTP_JOB_TTL_HOURS: job artifact retention time.
  • HEALTH_WAIT_SECONDS: internal service startup wait time in start_sam_http.sh.