# nvidia-proxy

**Repository Path**: csxlin/nvidia-proxy

## Basic Information

- **Project Name**: nvidia-proxy
- **Description**: NVIDIA NIM API Proxy for uni-agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NVIDIA API Proxy

HBuilderX 的 uni-agent 不支持直接调用 NVIDIA NIM 模型，本项目用一个 Python 中间服务做桥接，将 NVIDIA API 包装为 OpenAI 兼容格式，让 uni-agent 可以正常使用 NVIDIA 提供的模型（如 Qwen3 Coder 480B）。

## 快速开始

```bash
# 1. 安装依赖
pip install fastapi uvicorn httpx

# 2. 填写 API Key
echo "nvapi-your-key-here" > apikey.txt

# 3. 启动服务
python -m uvicorn service:app --host 127.0.0.1 --port 9000
```

服务启动后即可用 OpenAI 兼容的方式调用：

```bash
curl http://127.0.0.1:9000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder-480b",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

## 配置说明

### API Key

支持两种方式（环境变量优先）：

| 方式 | 说明 |
|------|------|
| 环境变量 `NVIDIA_API_KEY` | `export NVIDIA_API_KEY=nvapi-xxx` |
| `apikey.txt` 文件 | 写入一行 key 即可 |

### 模型映射 — `config.json`

所有可配置项都在 `config.json` 中，**无需改代码**即可增减模型：

```json
{
  "nvidia_base": "https://integrate.api.nvidia.com/v1",
  "model_mappings": {
    "qwen3-coder-480b": "qwen/qwen3-coder-480b-a35b-instruct",
    "deepseek-r1": "deepseek-ai/deepseek-r1",
    "llama-3.3-70b": "meta/llama-3.3-70b-instruct"
  },
  "default_model": "qwen3-coder-480b",
  "timeout": 180
}
```

| 字段 | 说明 |
|------|------|
| `nvidia_base` | NVIDIA API 基础地址 |
| `model_mappings` | **外部名称 → NVIDIA 真实名称** 的映射，调用方使用左侧简短名称 |
| `default_model` | 未指定模型时的默认值（取映射表的 key） |
| `timeout` | 请求超时时间（秒） |

### 如何更换/新增模型

只需编辑 `config.json`，在 `model_mappings` 中添加或修改一行即可：

```json
"model_mappings": {
  "my-model": "vendor/my-model-full-name"
}
```

然后在调用方使用 `"model": "my-model"` 即可。`/v1/models` 接口会自动返回所有已配置的模型列表。

## 接入 uni-agent

[uni-agent](https://doc.dcloud.net.cn/uni-app-x/ai/uni-agent.html) 是 DCloud 推出的 AI 编程助手，专为 uni-app / uni-app x 开发者打造，内置技能（Skills）、子智能体（Subagents）和知识库。它支持 `openai-compatible` 协议接入自定义模型服务，本代理正是为此而构建。

### 配置步骤

1. 在 HBuilderX 中打开 uni-agent（工具栏最右侧 AI 图标，或快捷键 `Ctrl+Alt+I`）
2. 进入 uni-agent **设置**，选择模型来源为 **自定义 Key**
3. 配置以下环境变量（参考 `uni-agent.txt`）：

```env
UNI_AGENT_BASE_URL=http://127.0.0.1:9000
UNI_AGENT_API_KEY=dummy-key
UNI_AGENT_PROVIDER=openai-compatible
UNI_AGENT_MODEL=openai-compatible/qwen3-coder-480b
UNI_AGENT_SMALL_FAST_MODEL=openai-compatible/qwen3-coder-480b
```

| 变量 | 必填 | 说明 |
|------|------|------|
| `UNI_AGENT_BASE_URL` | 是 | 本代理服务地址，**不含** `/v1`（uni-agent 会自动拼接） |
| `UNI_AGENT_API_KEY` | 是 | 随意填写，代理服务会自动替换为真实的 NVIDIA Key |
| `UNI_AGENT_PROVIDER` | 是 | 固定设为 `openai-compatible` |
| `UNI_AGENT_MODEL` | 是 | 主模型名，格式为 `openai-compatible/<映射key>` |
| `UNI_AGENT_SMALL_FAST_MODEL` | 否 | 快速小模型名，格式同上，可与主模型相同或配置另一个映射 |

> **注意**：`openai-compatible/` 前缀是 uni-agent 的要求，后面的 `qwen3-coder-480b` 对应 `config.json` 中的映射 key。

### 为什么需要这个代理

NVIDIA NIM API 的模型名格式（如 `qwen/qwen3-coder-480b-a35b-instruct`）与 OpenAI 不同，uni-agent 无法直接调用。本代理提供了：

1. **模型名映射** — 将简短名称转为 NVIDIA 完整名称
2. **协议适配** — 提供 OpenAI 兼容的 `/v1/chat/completions` 和 `/v1/models` 接口
3. **鉴权替换** — 调用方无需知道真实的 NVIDIA API Key
4. **强制流式** — 统一以 SSE 流式输出，提升交互体验

## 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/chat/completions` | 聊天补全（强制流式） |
| GET  | `/v1/models` | 返回可用模型列表 |

## 项目结构

```
nvidia-proxy/
├── service.py       # 主服务（FastAPI 应用）
├── config.json      # 模型映射 & 配置
├── apikey.txt       # NVIDIA API Key（不入库，需自行创建）
├── cmd.txt          # 启动命令备忘
├── uni-agent.txt    # uni-agent 环境变量配置参考
├── .gitignore       # 忽略敏感文件
└── README.md        # 本文档
```

## 注意事项

- `apikey.txt` 已加入 `.gitignore`，请勿将 Key 提交到版本库
- 所有请求强制流式输出（`stream: true`）
- 如果请求的模型名不在映射表中，会原样透传给 NVIDIA API
- uni-agent 中的 `UNI_AGENT_API_KEY` 可随意填写，代理会自动替换真实 Key