ising-calibration-setup
Use when connecting to the NVIDIA Ising Calibration model via the hosted API or a self-hosted NIM. Covers auth, keys and connectivity checks only.
Try your first task
A source-grounded starter task has not been verified for this skill yet.
SKILL.md
name: ising-calibration-setupdescription: >- Use when connecting to the NVIDIA Ising Calibration model via the hosted API or a self-hosted NIM. Covers auth, keys and connectivity checks only.license: Apache-2.0version: "0.1.0"permissions: [env, network, shell]tags: [nvidia, ising, quantum, calibration, nim, api, setup]metadata: author: "NVIDIA" version: "0.1.0" github-url: "https://github.com/NVIDIA/Ising" tags: [nvidia, ising, quantum, calibration, nim, api, setup]Ising Calibration Setup
Purpose
Get a user from zero to a verified working connection to the NVIDIA Ising Calibration model (Ising-Calibration-1.5-31B), in either of two ways:
- Hosted API on build.nvidia.com -- fastest, no GPU required.
- Self-hosted NIM container -- for on-premises, data-residency, or high-volume use, requires a supported NVIDIA GPU.
This skill is plumbing-scoped: getting a key, getting a 200 back, and
confirming that connection actually works. It stops there -- it does not
teach how to use the model (prompting it for calibration analysis, building
an agent workflow around it, etc.). See "Next steps" below for where that
guidance lives.
Instructions
Ask the user which they want (or infer it: "I don't have a GPU" -> hosted API;
"I need this on-prem / air-gapped / high volume" -> self-hosted NIM). Note that
the self-hosted container still needs internet access on its first run to
download the model weights. Then follow the matching section below
top-to-bottom. Full command sequences live in references/; this file only
handles routing, prerequisites, and the connectivity checklist.
Getting the credential is where users most often get stuck, and it happens in a browser where you cannot see what they see. Read the relevant reference doc in full before starting, then take them through one screen at a time, saying what they should expect to see and waiting for confirmation before moving on, rather than handing over a URL and waiting for them to return with a key. Never ask the user to paste a key into the conversation; have them load it into their own shell and verify it there.
Name the two setups when talking to the user: "the hosted API at build.nvidia.com" and "a self-hosted NIM container". Refer to each step by what it does ("generating an NGC personal key", "pulling the NIM container") rather than by its number in the lists below.
When to use
- "How do I connect to Ising Calibration?"
- "Set up the Ising Calibration model"
- "Get an API key for build.nvidia.com / Ising"
- "Run / self-host the Ising Calibration NIM" (own hardware or a cloud GPU instance)
- "My Ising Calibration API calls are failing, check my setup"
- "/ising-calibration-setup"
Prerequisites (either setup)
- An NVIDIA account (create one at build.nvidia.com or ngc.nvidia.com if the user does not have one).
curlavailable locally for connectivity checks.jq, only if the user wants the optional hello-world request at the end. The reference docs give apython3fallback if it is not installed.
Hosted API (build.nvidia.com)
No GPU needed; requests are billed/rate-limited against the hosted endpoint.
- Sign in at
https://build.nvidia.com. - Generate a personal API key: profile menu -> Settings -> API keys ->
Generate API Key (or go directly to
https://build.nvidia.com/settings/api-keys). You will be asked to name the key and set an expiration. The key starts withnvapi-and is shown only once -- store it immediately without letting it land in shell history (seereferences/hosted-api-quickstart.mdfor aread -rs-based method). - The model page, for rate limits and current terms:
https://build.nvidia.com/nvidia/ising-calibration-1.5-31b. - Follow
references/hosted-api-quickstart.mdfor the endpoint, the request format, and a workingcurlexample.
Governed by the NVIDIA API Trial Terms of Service.
Self-hosted NIM container
Requires an NVIDIA Ada Lovelace, Hopper, or Blackwell GPU with enough memory (see
the reference doc for tested configurations), plus Docker with the NVIDIA
Container Toolkit installed -- docker run --gpus all fails without it.
Walk the user through these rather than summarizing them; the full walkthrough
is in references/self-hosted-nim-quickstart.md,
which you should read before starting.
-
Sign in at
https://org.ngc.nvidia.com. -
Go to
https://org.ngc.nvidia.com/setup/personal-keys(or: account icon -> Setup -> Generate Personal Key) and click Generate Personal Key. -
Fill in the dialog's three required fields: Key Name, Expiration, and Services Included -- a dropdown of per-service checkboxes. NGC Catalog is the only scope needed; it grants pulls from the public nvcr.io catalog, and without it
docker loginfails with an auth error even though the key is valid. -
The key is shown once. Have the user copy it and load it into their shell with
read -rs NGC_API_KEY(notexport NGC_API_KEY=..., which lands the raw key in shell history), then confirm it is set with a check that does not print it:test -n "$NGC_API_KEY" && echo set.This is a separate credential from the
nvapi-key used for the hosted API. If the user already has annvapi-key, tell them it will not work here and they need to generate this one as well. -
Log Docker in to the NVIDIA container registry -- this is also the check that the key and its scopes are right, so do it before pulling anything:
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdinExpectLogin Succeeded. If it fails, fix the key here rather than continuing to the pull. -
Pull and run the container, then confirm it is serving. Use the
docker runfrom the quickstart as written, including-e NGC_API_KEY=$NGC_API_KEY, which passes the key into the container. Full command, GPU/memory requirements, health check, and example request are inreferences/self-hosted-nim-quickstart.md. -
Run the connectivity checklist. You can then offer the optional hello-world request below, the same as for the hosted API.
Connectivity checklist
Run this for either setup to confirm the connection actually works, and to tell
an auth failure apart from a network/model-not-ready failure. Full checklist
with copy-pasteable commands: references/connectivity-checklist.md.
Summary:
- Hosted API: confirm
NVIDIA_API_KEYis set and non-empty. Self-hosted NIM: there is no request-time key --NGC_API_KEYis used for the image pull and passed into the container at startup, not sent with requests -- so confirm the container is running and ready instead. - Send one lightweight request against the endpoint.
- A
401/403means different things per setup. Hosted API: the key is missing, wrong, or expired -- regenerate it. Self-hosted NIM: the container itself never returns 401, so a proxy, gateway, or load balancer in front of it is rejecting the request -- check that layer, not the NGC key. - A connection-refused/timeout against a self-hosted NIM means the container
is not up yet or the port mapping is wrong -- check
docker psand container logs before assuming an auth problem.
Hello world: an optional first real request
A 200 from the connectivity checklist is the bar for a working connection --
setup is done at that point. A text ping does not exercise the multimodal path
though, so a real calibration-plot request is a useful way to see the connection
do the model's actual job. Offer it for either setup and let the user decide
whether to run it. Each reference has a "Hello world" section with the request:
- Hosted API:
references/hosted-api-quickstart.md - Self-hosted NIM:
references/self-hosted-nim-quickstart.md
Both pull a real sample image from the public QCalEval benchmark dataset, so no
local test image is needed. The request shape is the same either way; only the
endpoint and model ID differ -- read the self-hosted ID from /v1/models rather
than copying the hosted string across.
Examples
- "I don't have a GPU, how do I try Ising Calibration?" -> hosted API path:
generate an nvapi- key, store it as
NVIDIA_API_KEY, verify with the curl ping inreferences/hosted-api-quickstart.md. - "Run the Ising Calibration NIM on our H200 box" -> self-hosted path: generate
an NGC personal key with the NGC Catalog scope,
docker login, pull and run the container, wait for/v1/health/ready. - "My calls return 401" -> connectivity checklist: establish which setup first, then follow the matching Troubleshooting entry below.
Next steps
Once the connectivity checklist passes, this skill's job is done -- you have a working, authenticated connection. What to do with it is out of scope here; go to:
- Building an agentic calibration workflow? Start with the Quantum Calibration Agent Blueprint -- an end-to-end workflow built on this model.
- Want the other models in this family (decoders, other calibration sizes)? Browse the Hugging Face collection.
- Training or optimizing a predecoder? See the Ising-Decoding cookbook.
Limitations
- Hosted API rate limits and pricing are not published in this skill; check the build.nvidia.com model page for current terms.
- GPU memory requirements vary by GPU family -- see
references/self-hosted-nim-quickstart.mdfor the tested configurations.
Troubleshooting
- Error:
401 Unauthorizedon the hosted API. Cause: missing/expiredNVIDIA_API_KEY, or using the NGC key instead of thenvapi-key. Solution: regenerate atbuild.nvidia.com/settings/api-keys. - Error:
docker loginordocker pullfails with auth error. Cause: missing/expiredNGC_API_KEY(or set in a different shell than the one runningdocker login); using thenvapi-key instead of the NGC key; or a key whose service scopes omit NGC Catalog. Solution: check the scope before assuming the key is bad -- a wrongly-scoped key fails identically to an invalid one. Regenerate atorg.ngc.nvidia.com/setup/personal-keyswith NGC Catalog included. - Error:
docker loginsucceeds butdocker pullreturns 401 or "not found". Cause: the credential is fine but the image is not visible to the account, typically an unaccepted access agreement on the catalog page. Solution: have the user open the catalog page while signed in to confirm the image is visible to their account. - Error:
401/403from a self-hosted NIM endpoint. Cause: the container does not authenticate requests, so the rejection comes from a reverse proxy, API gateway, or load balancer in front of it. Solution: check that layer's configuration and credentials. To confirm, bypass it: on the machine running Docker, curllocalhost:<host-port>, where the host port is the left side of the-pflag shown bydocker ps(8000 if the quickstart command was used unchanged). A200there proves the container is fine and the 401 comes from the layer in front. Regenerating the NGC key does not help here. - Error: container starts but the startup weight download fails.
Cause: the weights come from public Hugging Face, so the usual cause is
outbound network access from the container (proxy, firewall, DNS, or
huggingface.co blocked). Solution: check
docker logs <container>for the failing URL and fix egress. - Error: connection refused on
localhost:8000(or whichever host port was mapped). Cause: NIM container still loading weights, crashed, or the-phost port does not match the one being curled. Solution: checkdocker psanddocker logs <container>; wait for/v1/health/readyto return200before sending requests. - Error:
Insufficient GPU memory/ OOM on container start. Cause: the GPU does not have enough memory for any configuration the container can run. Solution: use a GPU with more memory, or more GPUs; see the tested configurations inreferences/self-hosted-nim-quickstart.md.