← Back to skills

CURATED FROM PUBLIC GIT

ising-calibration-setup

>-

↓ 0★ 0by greatsage_sh
4fbbff39da1a
skillmarket install greatsage_sh/ising-calibration-setup
Public Git sourcehttps://github.com/NVIDIA/skills.gitcommit 4fbbff39da1a5780d8bfd796f1674618c6349ef7
Part of skillsetskills →

About this skill

---
name: ising-calibration-setup
description: >-
  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.0
version: "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).
- `curl` available locally for connectivity checks.
- `jq`, only if the user wants the optional hello-world request at the end. The
  reference docs give a `python3` fallback if it is not installed.

## Hosted API (build.nvidia.com)

No GPU needed; requests are billed/rate-limited against the hosted endpoint.

1. Sign in at `https://build.nvidia.com`.
2. 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
   with `nvapi-` and is shown only once -- store it immediately without
   letting it land in shell history (see
   [`references/hosted-api-quickstart.md`](references/hosted-api-quickstart.md)
   for a `read -rs`-based method).
3. The model page, for rate limits and current terms:
   `https://build.nvidia.com/nvidia/ising-calibration-1.5-31b`.
4. Follow [`references/hosted-api-quickstart.md`](references/hosted-api-quickstart.md)
   for the endpoint, the request format, and a working `curl` example.

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`](references/self-hosted-nim-quickstart.md),
which you should read before starting.

1. Sign in at `https://org.ngc.nvidia.com`.
2. Go to `https://org.ngc.nvidia.com/setup/personal-keys` (or: account icon ->
   Setup -> Generate Personal Key) and click **Generate Personal Key**.
3. 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 login` fails with an auth error even though the key is
   valid.
4. The key is shown **once**. Have the user copy it and load it into their shell
   with `read -rs NGC_API_KEY` (not `export 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 an `nvapi-` key, tell them it will not work here
   and they need to generate this one as well.
5. 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-stdin`
   Expect `Login Succeeded`. If it fails, fix the key here rather than
   continuing to the pull.
6. Pull and run the container, then confirm it is serving. Use the `docker run`
   from 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 in
   [`references/self-hosted-nim-quickstart.md`](references/self-hosted-nim-quickstart.md).
7. 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`](references/connectivity-checklist.md).

Summary:

1. Hosted API: confirm `NVIDIA_API_KEY` is set and non-empty. Self-hosted NIM:
   there is no request-time key -- `NGC_API_KEY` is 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.
2. Send one lightweight request against the endpoint.
3. A `401`/`403` means 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.
4. A connection-refused/timeout against a self-hosted NIM means the container
   is not up yet or the port mapping is wrong -- check `docker ps` and
   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`](references/hosted-api-quickstart.md)
- **Self-hosted NIM**: [`references/self-hosted-nim-quickstart.md`](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 in `references/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](https://github.com/NVIDIA/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](https://huggingface.co/collections/nvidia/nvidia-ising).
- **Training or optimizing a predecoder?** See the
  [Ising-Decoding cookbook](https://github.com/NVIDIA/Ising-Decoding).

## 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.md` for the tested configurations.

## Troubleshooting

- **Error**: `401 Unauthorized` on the hosted API. **Cause**: missing/expired
  `NVIDIA_API_KEY`, or using the NGC key instead of the `nvapi-` key.
  **Solution**: regenerate at `build.nvidia.com/settings/api-keys`.
- **Error**: `docker login` or `docker pull` fails with auth error. **Cause**:
  missing/expired `NGC_API_KEY` (or set in a different shell than the one
  running `docker login`); using the `nvapi-` 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 at `org.ngc.nvidia.com/setup/personal-keys` with NGC
  Catalog included.
- **Error**: `docker login` succeeds but `docker pull` returns 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`/`403` from 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, curl `localhost:<host-port>`, where the host
  port is the left side of the `-p` flag shown by `docker ps` (8000 if the
  quickstart command was used unchanged). A `200` there 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
  `-p` host port does not match the one being curled.
  **Solution**: check `docker ps` and `docker logs <container>`; wait for
  `/v1/health/ready` to return `200` before 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 in `references/self-hosted-nim-quickstart.md`.