Getting Started
This page shows how to authenticate with NGC, launch the 3D Body Pose NIM container, and configure its runtime.
Prerequisites
To ensure that you have the supported hardware and software stack, check the Support Matrix.
NGC Authentication
An NGC API key is required to pull the container image and download models. Complete the following steps to create the key, export it, and log in to the NVIDIA Container Registry.
Generate an API Key
An NGC API key is required to access NGC resources. You can generate a key at https://org.ngc.nvidia.com/setup/api-keys.
When creating an NGC API Personal key, ensure that at least NGC Catalog is selected from the Services Included dropdown. You can include more services if this key is to be reused for other purposes.
Personal keys allow you to configure an expiration date, revoke or delete the key using an action button, and rotate the key as needed. For more information about key types, refer to NGC API Keys in the NGC User Guide.
Export the NGC API Key
Pass the value of the API key to the docker run command in the next section as the NGC_API_KEY environment variable to download the appropriate models and resources when starting the NIM.
The simplest way to create the NGC_API_KEY environment variable is to export it in your terminal:
To make the key available in later sessions, store it in a file that only you can read and export it from that file in your shell startup file:
A password manager works the same way, for example export NGC_API_KEY="$(pass show nvidia/ngc)".
Docker Login to NGC
To pull the NIM container image from NGC, first authenticate with the NVIDIA Container Registry with the following command:
Use $oauthtoken as the username and NGC_API_KEY as the password. The $oauthtoken username is a special name that indicates that you will authenticate with an API key and not a user name and password.
Launching the NIM Container
The following commands launch the 3D Body Pose NIM container with the gRPC service. For a list of parameters, refer to Runtime Parameters for the Container.
Create the host cache directory yourself before the first launch so the model download persists across runs. If Docker creates the directory for you, it is owned by root and the container exits with a permission error. LOCAL_NIM_CACHE can be any directory you own.
The container runs as uid 1000, so the directory needs a+rwX. If the container exits reporting that the model download target is not writable, the directory most likely belongs to another user, so change the first line of the launch commands to a directory directly under your home, for example export LOCAL_NIM_CACHE=~/nim-cache, and run them again. For details, refer to Model Caching.
Launch the container:
The flag --gpus all is used to assign all available GPUs to the NIM container.
To assign specific GPUs to the NIM container (in case of multiple GPUs available in your machine), use --gpus '"device=0,1,2..."'.
The first launch takes longer than later ones: the container image is several gigabytes to pull, and on the first start the server downloads the model into the mounted cache before it binds its ports — the startup log reads holds no engines yet while it does. Later launches from a populated cache reach SERVING much faster.
If the NIM launch is successful, you get a response similar to the following:
The inference server’s own log lines follow. The line Health: NOT_SERVING appears early, when the gRPC service starts and before the warmup. The final startup lines include, in this order, Triton warmup done in {seconds}s (engines loaded), enable_contact startup latch done: loaded={bool} (from BODY_POSE_ENABLE_CONTACT), and Health: SERVING. These lines have this shape:
The NIM launcher’s own lines, such as Waiting for backend readiness, use the plain form INFO:inference:{message} instead.
OpenTelemetry is off by default. To write these lines as OpenTelemetry log records instead, one JSON object per message among span and metric records, add -e NIM_ENABLE_OTEL=1 to the docker run command. See Advanced Tuning Variables for the OpenTelemetry variables.
The NIM runs a warmup pass before it reports ready. Until the warmup completes, /v1/health/ready returns 503 and the gRPC port does not accept connections yet; once it does, the gRPC health service reports SERVING. Poll /v1/health/ready, or retry the gRPC health check until it connects, before sending inference requests. Then run the Quick Test before the full sample.
Model Manifest Profiles
By default, the NIM selects the model profile that matches the compute capability of the detected GPU. One profile is published per architecture.
NIM_MODEL_PROFILE is optional. To pin a profile, first list the profiles in the image you pulled with the list-model-profiles utility:
Then add the ID to the launch command:
If NIM_MODEL_PROFILE is set, ensure that the GPU architecture it targets matches the hardware. With an incorrect profile ID the container exits after NV_AI4M_MODEL_READY_TIMEOUT_S (default 120 seconds) with Model validation failed after <n>s (gpu_cc=<cc>, ...). If left unset, the NIM selects a matching profile automatically.
Environment Variables
The following table describes the environment variables that can be passed into a NIM as a -e argument added to a docker run command:
For the remaining tuning variables, refer to Advanced Tuning Variables.
Runtime Parameters for the Container
The following table describes the docker run flags used to launch the 3D Body Pose NIM container.
Stopping the Container
The launch commands on this page do not use --rm, so stop the container and then
remove it: