MinT Quickstart
English | 中文
The single entry repo for learning MinT (Mind Lab Toolkit) — from first API call to advanced RL training.
Visit the MinT website.
Important: All experiments run against an already deployed MinT server. This repo does not start MinT backend services locally. You only need valid server endpoint + API key credentials.
Demo Portfolio
Available Now
Reference
| Demo |
Track |
Why it exists |
Script |
| OpenPI FAST HTTP |
Embodied |
Shows the raw wire protocol directly for debugging and request-shape reference |
demos/embodied/openpi_vla_http.py |
Coming Soon
| # |
Demo |
Track |
Description |
Status |
| 6 |
VLM-1 Vision QA |
VLM |
Image + question -> grounded answer |
Planned (M2) |
| 7 |
VLM-2 Vision Instruction |
VLM |
Image + task -> action/decision |
Planned (M2) |
Quick Start
Requirements: Python >= 3.11, a MinT API key
pip install git+https://github.com/MindLab-Research/mindlab-toolkit.git python-dotenv matplotlib numpy
Create .env in the repo root:
MINT_API_KEY=sk-your-api-key-here
Use the MinT endpoint that matches your region:
- Mainland China:
https://mint-cn.macaron.xin/
- Outside Mainland China:
https://mint.macaron.xin/
OpenAI-Compatible Inference
If you only want to run inference against an already-deployed model, you do not
need the mint SDK at all. MinT serves an OpenAI-compatible endpoint at
/oai/api/v1, so the official openai SDK works by overriding base_url:
pip install openai
MINT_BASE_URL=https://mint.macaron.xin \
MINT_API_KEY=sk-your-api-key-here \
python quickstart/openai_compat.py chat \
--model Qwen/Qwen3-30B-A3B-Instruct-2507 \
--user-message "Reply with exactly: pong"
Subcommands: completions, chat, tool, smoke. Supported surface includes
models.list/retrieve, completions, chat, tool-call roundtrips, and
AsyncOpenAI. Not yet supported: stream=True, n > 1, responses.create,
embeddings.create. See the
OpenAI-Compatible API docs for the full
guide.
Common First Questions
Should I use SFT or RL?
- Use SFT when you already know what the model should say or do and you have labeled target outputs.
- Use RL when you do not have one fixed target answer but you can score the model's behavior with a reward, verifier, test suite, or environment feedback.
- If you have both, you can combine them. The common pattern is SFT for the basic behavior, then RL for optimization, but that is not a required order for every task.
Does MinT support SFT?
Yes. MinT supports SFT directly.
The standard SFT path is:
forward_backward(..., loss_fn="cross_entropy")
optim_step(...)
Which domain should I use?
Choose by your network path:
- Mainland China ->
https://mint-cn.macaron.xin/
- Outside Mainland China ->
https://mint.macaron.xin/
If you are unsure, try the one that matches your region first. The practical goal is lower latency and stable connectivity.
Where do I get MINT_API_KEY?
MINT_API_KEY is currently issued by the Mind Lab team.
To request access:
- go to
https://macaron.im/mindlab
- use Schedule a Demo
- or email
contact@mindlab.ltd
Run the quickstart (SFT then RL in one script):
python quickstart/quickstart.py
Or open the interactive notebook:
jupyter notebook quickstart/mint_quickstart.ipynb
Or run a focused quickstart recipe:
python quickstart/custom_reward.py
python quickstart/custom_loss.py
Run a Demo
python demos/rl/adapters/verifiable_math.py # RL-1: math with exact-match reward
python demos/rl/adapters/preference_chat.py # RL-2: chat with helpfulness proxy
python demos/rl/adapters/environment_tooluse.py # RL-3: code gen with execution reward
python demos/embodied/openpi_vla_sdk.py # Embodied-1: OpenPI via mintx / mint.mint
python demos/embodied/openpi_vla_http.py # Reference: raw OpenPI FAST HTTP wire shape
All demos are configurable via environment variables. See demos/rl/README.md for details.
Advanced Workflows
Checkpoint Loop (Save -> Download -> Upload -> Resume)
If you want a full checkpoint lifecycle:
python advanced/checkpoint.py save --name my-ckpt
python advanced/checkpoint.py download tinker://<run-id>/weights/<ckpt-name> -o ./ckpts
python advanced/checkpoint.py upload ./ckpts/<archive>.tar.gz
python advanced/checkpoint.py resume tinker://<run-id>/weights/<ckpt-name> --with-optimizer --steps 3
See advanced/README.md for the full command matrix, the optimizer-preserving resume shape (create_lora_training_client(...) + load_state_with_optimizer(...)), and guardrails (sampler_weights vs weights).
MIS Rollout Correction Validation
If you want a focused end-to-end check for session-level Seq-MIS wiring:
python advanced/validate_mis_rollout_correction.py --base-model Qwen/Qwen3-30B-A3B-Instruct-2507
See docs/mis_rollout_correction.md for prerequisites, env vars, expected output, and failure modes.
Queue Status Polling
Monitor queue position and estimated wait time for pending sample requests:
python advanced/queue_status.py
Uses the low-level AsyncTinker client with backpressure headers to read queue fields from 408 responses.
Repo Structure
mint-quickstart/
.env.example # Template for API key configuration
quickstart/
quickstart.py # SFT -> RL in one script
custom_reward.py # Client-side reward shaping + importance_sampling
custom_loss.py # Pairwise preference training via forward_backward_custom
sampling_log.py # Train then inspect model responses
mint_quickstart.ipynb # Interactive notebook version
demos/
rl/ # 3 RL demos (available)
rl_core.py # Shared GRPO training loop
adapters/
verifiable_math.py
preference_chat.py
environment_tooluse.py
vlm/ # 2 VLM demos (coming soon)
embodied/ # primary SDK demo + low-level HTTP reference
advanced/ # Checkpoint workflows, MIS validation, queue status
docs/
roadmap.md # 6-demo roadmap with status tags
troubleshooting.md # Common issues and fixes
migration-from-minT-demo.md
experiments/ # Validation reports for quickstart flows
.pi/
skills/ # Project-local pi skills for API, debugging, and issue reporting
mint-skill/ # AI coding agent migration skill
Tinker SDK Compatibility
If you have existing code using import tinker, the lowest-friction MinT migration is:
Then point the Tinker-style client surface at MinT:
TINKER_BASE_URL=<your-region-endpoint>
TINKER_API_KEY=<your-mint-api-key>
Use the MinT endpoint that matches your region:
- Mainland China:
https://mint-cn.macaron.xin/
- Outside Mainland China:
https://mint.macaron.xin/
Why this is the recommended path:
- raw upstream
import tinker still validates API keys with the tml- prefix
- MinT API keys start with
sk-
import mint as tinker keeps the Tinker-style code shape while enabling MinT compatibility patches
If you must keep the exact import tinker statement, import mint earlier in the same process before constructing Tinker clients.
Docs