跳到主要内容

NIM x Code Agent

本 Cookbook 介绍如何通过 NIM + LiteLLM Proxy 将 MiniMax-M2.5 接入 Claude Code 和 OpenAI Codex CLI，让 Code Agent 使用本地部署的大模型进行代码生成与辅助开发。

架构​

Claude Code (Anthropic Messages API)     Codex CLI (OpenAI Chat Completions API)
           │                                          │
           └──────────────┐          ┌────────────────┘
                          ▼          ▼
                   LiteLLM Proxy (:4000)
                   ┌─────────────────────┐
                   │  Model name mapping  │
                   │  Format translation  │
                   │  Param sanitization  │
                   └─────────┬───────────┘
                             ▼
                    NVIDIA NIM (:8000)
                   ┌─────────────────────┐
                   │  MiniMax-M2.5       │
                   │  OpenAI-compatible  │
                   └─────────────────────┘

LiteLLM 在其中负责：

  • 将 Anthropic Messages API 格式转换为 OpenAI Chat Completions 格式
  • 将 Claude/GPT 模型名映射到 NIM 后端
  • 过滤 NIM 不支持的参数（如 strict、additionalProperties）
  • 合并 MiniMax-M2.5 的 <think> 推理内容到正常输出

前置条件​

  • Docker + NVIDIA Container Toolkit（nvidia-ctk）
  • 足够 VRAM 的 GPU（MiniMax-M2.5 需要多卡）
  • NGC API Key（https://org.ngc.nvidia.com）

快速部署​

1. 配置环境变量​

cp .env.example .env
# 编辑 .env，填入 NGC_API_KEY

.env 内容示例：

NGC_API_KEY=nvapi-xxxxxxxxxxxx
LITELLM_MASTER_KEY=sk-litellm-master-key   # 可自定义

2. 启动服务​

docker compose up -d

NIM 模型加载需要几分钟，确认就绪：

docker logs -f hello-vibe-nim-1
# 等待出现：Uvicorn running on http://0.0.0.0:8000

3. 验证​

curl http://localhost:4000/health/liveliness
# {"status": "healthy"}

Docker Compose 配置说明​

services:
  nim:
    image: nvcr.io/nvstaging/nim/minimax-m2-5:refresh-dev3.fix2
    ports:
      - "8000:8000"
    environment:
      NGC_API_KEY: ${NGC_API_KEY:?NGC_API_KEY is required}
      NIM_SERVER_PORT: "8000"
    volumes:
      - /raid/models/nim-cache:/opt/nim/.cache   # 模型缓存目录
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    shm_size: "16gb"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/v1/health/ready"]
      interval: 30s
      start_period: 300s   # 给模型加载留足时间

  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    ports:
      - "4000:4000"
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    environment:
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:-sk-litellm-master-key}
    depends_on:
      nim:
        condition: service_healthy   # 等 NIM 健康后再启动

LiteLLM 路由配置说明​

litellm-config.yaml 中，所有模型别名均指向同一个 NIM 后端：

model_list:
  - model_name: claude-sonnet-4-6        # Claude Code 请求的模型名
    litellm_params: &nim
      model: nvidia_nim/MiniMaxAI/MiniMax-M2.5
      api_base: http://nim:8000/v1
      api_key: not-used
      stream: true
      merge_reasoning_content_in_choices: true   # 合并 <think> 推理内容

  - model_name: o3                       # Codex CLI 请求的模型名
    litellm_params: *nim                 # 复用同一套参数

litellm_settings:
  drop_params: true
  additional_drop_params:
    - "tools[*].function.strict"                          # NIM 不支持
    - "tools[*].function.additionalProperties"
    - "tools[*].function.parameters.additionalProperties"
  num_retries: 3
  request_timeout: 600

配置 Claude Code​

首次使用跳过引导页​

echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

启动 Claude Code​

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-litellm-master-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-20250514"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-20250514"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

claude

写入 shell profile 持久化：

cat >> ~/.bashrc << 'EOF'
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-litellm-master-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-20250514"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-20250514"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5-20251001"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
EOF
source ~/.bashrc

关键环境变量说明​

变量作用
ANTHROPIC_BASE_URL指向 LiteLLM，完成 Anthropic → OpenAI 格式转换
ANTHROPIC_AUTH_TOKENLiteLLM master key 认证
ANTHROPIC_DEFAULT_SONNET_MODEL锁定 Sonnet 模型版本
ANTHROPIC_DEFAULT_OPUS_MODEL锁定 Opus 模型版本
ANTHROPIC_SMALL_FAST_MODEL锁定 Haiku（小/快模型）版本
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS禁用 extended thinking 等 beta 功能

配置 Codex CLI​

export OPENAI_BASE_URL="http://localhost:4000/v1"
export OPENAI_API_KEY="sk-litellm-master-key"

codex --model o3

支持的模型别名​

所有别名均路由到 NIM 后端的 MiniMax-M2.5：

Claude Code 模型： claude-opus-4-6-20260205, claude-opus-4-6, claude-sonnet-4-6, claude-sonnet-4-5-20250929, claude-opus-4-20250514, claude-sonnet-4-20250514, claude-haiku-4-5-20251001, claude-haiku-4-5, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022

Codex 模型： gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5-codex, codex-mini-latest

OpenAI 系列： gpt-5.4, gpt-5.4-pro, gpt-5, gpt-5-mini, gpt-4.1, gpt-4.1-mini, gpt-4o, o3, o3-pro, o3-mini, o4-mini

常见问题排查​

Auth 冲突警告​

如果 Claude Code 提示 "Both a token and an API key are set"：

unset ANTHROPIC_API_KEY

工具调用参数报错​

tools -> function -> strict: Input should be a valid boolean — 已通过 litellm-config.yaml 中的 drop_params: true 自动处理，使用 nvidia_nim/ provider 前缀可自动过滤不兼容参数。

空响应​

MiniMax-M2.5 是推理模型，输出含 <think> 标签。merge_reasoning_content_in_choices: true 会将推理内容合并到正常输出。若仍出现空响应，确认已设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

查看服务日志​

docker logs hello-vibe-litellm-1 --tail 50
docker logs hello-vibe-nim-1 --tail 50
最后于 更新