UpscaleX

UpscaleX MCP/CLI

UpscaleX 是一款面向生产环境的 8K 和 16K 图像放大命令行工具及模型上下文协议（MCP）服务，由 RealESRGAN、Vulkan GPU 硬件加速和 Lanczos 超采样驱动。

专为数字印刷工作流、大幅面海报制作、艺术品复制，以及在 Claude Desktop、Antigravity 和 Cursor 中自主运行的 AI 编码 Agent 而设计。

想要快速设置？请阅读安装指南，其中提供了可复制粘贴的 AI Agent 设置提示词和手动说明；也可以向 AI 编码助手提供 UpscaleX Agent Skill。

---

目录

• 主要功能
• 安装指南
• AI Agent 技能
• 视觉质量对比
• 文档目录
• 使用 uv 快速入门
• 命令行界面
• 模型上下文协议（MCP）集成
• 模型矩阵
• 测试与验证
• 参与贡献
• 许可证

---

主要功能

• 双模式运行：交互式命令行界面（upscalex）和标准模型上下文协议服务（upscalex-mcp）。
• 8K 和 16K 预设：
  • 16K：采用原生 4x RealESRGAN 深度学习模型放大，生成高达 4 亿像素以上的母版文件。
  • 8K：先进行 4x 深度学习推理，再使用 Lanczos-3 降采样（超采样抗锯齿 / SSAA），实现清晰边缘和零噪点。
  • 自定义尺寸：按比例缩放至任意分辨率，或适配实体印刷品的纵横比。
• 跨平台架构：已在 Windows、Linux（Ubuntu、Debian、Fedora）和 macOS（Apple Silicon arm64 与 Intel x86_64）上测试并获得支持。
• GPU 加速，支持无缝回退至 CPU：自动发现并使用独立 Vulkan GPU（NVIDIA RTX/GeForce、AMD Radeon、Intel Arc/Iris，以及通过 MoltenVK 支持的 Apple Silicon）。在无头 Docker 容器或没有 GPU 驱动的环境中，图像引擎会回退至多线程 CPU Lanczos 超分辨率处理，不会发生崩溃。
• 硬件诊断：集成的 upscalex doctor 命令可检查系统计算设备、Vulkan 支持情况和推荐的分块尺寸。
• 内存安全分块：采用滑动窗口空间分块（--tile-size 256），可在 4GB 至 8GB GPU 上处理超千兆像素图像，避免内存不足（OOM）错误。
• 自动配置图像引擎：如果本地找不到预编译的平台二进制文件，会自动下载并验证。
• 印刷精度分析：自动按 300 DPI、150 DPI 和 72 DPI 计算以英寸和厘米为单位的实体印刷尺寸。

---

视觉质量对比

以下为实测对比，展示 UpscaleX 使用 realesrgan-x4plus 模型，将低分辨率像素化源图（663 × 531 px，0.35 MP）进行 4 倍超分辨率重建，提升至适合高清打印的分辨率（2,652 × 2,124 px，5.63 MP）。

指标	原始源图	UpscaleX 4 倍输出
像素尺寸	663 × 531	2,652 × 2,124
总百万像素数	0.35 MP	5.63 MP（像素数增加 16 倍）
边缘重建	严重的块状像素化、振铃	重建圆形辐条，轮廓清晰
最大 300 DPI 打印尺寸	2.2 × 1.8 英寸	8.8 × 7.1 英寸
模型	—	realesrgan-x4plus
硬件	—	NVIDIA GeForce RTX 3050 Laptop GPU（10.8s）

---

文档目录

docs/ 目录和仓库根目录中提供了全面的技术指南：

• 安装指南：AI Agent 自主复制粘贴提示词和手动安装流程。
• AI Agent 技能规范：适用于 Claude、Cursor 和 Antigravity 的标准 Agent 技能定义。
• CLI 参考指南：完整的标志说明、分块策略和执行示例。
• 模型上下文协议（MCP）指南：JSON-RPC 工具契约、参数架构和多客户端配置。
• 架构与数学规范：深度学习基础、RRDB 网络、Lanczos 核和内存界限。
• 错误处理与故障排查：已知故障模式、运行前清理和恢复流程。
• 贡献指南：代码规范、测试流程和拉取请求工作流。

---

快速开始

选项 1：从 PyPI 安装（最适合 CLI 和 MCP）

pip install upscalex

选项 2：克隆并从源代码安装（使用 uv）

git clone https://github.com/The-Open-Source-Founder/upscalex.git
cd upscalex

# Create virtual environment and install package
uv venv
uv pip install -e .

查看可用模型

upscalex models

---

命令行界面

16K 放大（默认 4 倍模型）

upscalex upscale input.png --target 16k

8K 超采样放大

upscalex upscale poster.png --target 8k -o poster_8k.png

2D 插画／动漫作品

upscalex upscale graphic.png --model realesrgan-x4plus-anime --target 8k

图像与打印尺寸检查

upscalex info input.png

硬件与内容感知模型推荐

upscalex recommend input.png

完整选项和参数请参阅 CLI 指南。

---

模型上下文协议（MCP）集成

UpscaleX 通过 stdio 作为原生 MCP 服务运行，使 AI Agent（Claude Desktop、Cursor、Antigravity、Windsurf、Zed）能够检查图像元数据、评估打印可行性并自主执行放大。

服务调用

# Standalone entrypoint
upscalex-mcp

# Or via CLI
upscalex serve

客户端配置

方法 1：使用 Pip（pip install upscalex）

A. Claude Desktop

配置文件路径：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "upscalex": {
      "command": "upscalex-mcp"
    }
  }
}

注意：如果你的环境未将全局 pip 二进制文件加入 PATH，请使用显式 Python 命令：

{
  "mcpServers": {
    "upscalex": {
      "command": "python",
      "args": ["-m", "upscalex.server"]
    }
  }
}

B. 默认／常见 MCP 客户端（Cursor、Antigravity、Windsurf、Claude Code）

配置文件：mcp_config.json 或 .cursor/mcp.json

{
  "mcpServers": {
    "upscalex": {
      "command": "upscalex-mcp"
    }
  }
}

---

方法 2：使用 Git 克隆和源代码检出

A. Claude Desktop（使用 uv 或 virtualenv）

{
  "mcpServers": {
    "upscalex": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/upscalex",
        "upscalex-mcp"
      ]
    }
  }
}

直接使用虚拟环境的替代方案（Windows／Linux／macOS）：

{
  "mcpServers": {
    "upscalex": {
      "command": "/absolute/path/to/upscalex/.venv/bin/python",
      "args": ["-m", "upscalex.server"]
    }
  }
}

（在 Windows 上，使用 C:\\absolute\\path\\to\\upscalex\\.venv\\Scripts\\python.exe）

B. 默认／常见 MCP 客户端（Cursor、Antigravity、Windsurf）

配置文件：mcp_config.json 或 .cursor/mcp.json

{
  "mcpServers": {
    "upscalex": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/upscalex",
        "upscalex-mcp"
      ]
    }
  }
}

完整工具架构和 JSON-RPC 契约请参阅 MCP 指南。

---

模型矩阵和目录

UpscaleX 支持预打包核心模型和按需下载的社区模型：

模型 ID	倍率	目标媒体	显存要求	状态	描述
realesrgan-x4plus	4x	照片 / 艺术作品	中（4GB 显存）	已安装	旗舰模型，适用于高保真摄影作品、艺术作品和展览海报。
realesrgan-x4plus-anime	4x	动漫 / 插画	中（4GB 显存）	已安装	保留 2D 插画中的平涂色彩、清晰轮廓和线条细节。
realesr-animevideov3-x4	4x	视频 / 快速预览	低（1GB-2GB / CPU）	已安装	轻量级 4x 前馈模型，适用于快速处理和低配置系统。
realesr-animevideov3-x2	2x	动画 / 视频	低（1GB-2GB / CPU）	已安装	快速 2x 模型，适用于视频帧、图标和轻量级 Web 资源。
realesr-animevideov3-x3	3x	动画 / 视频	低（1GB-2GB / CPU）	已安装	快速 3x 模型，适用于中间倍率缩放。
realesr-general-x4v3	4x	通用 / 紧凑	低（2GB 显存）	已安装	官方紧凑型通用模型，内存占用低。
4x-ultrasharp	4x	肖像 / 超高细节	中高（4GB-6GB）	可下载	社区热门模型，适用于微观纹理、肖像、织物和皮肤。
4x-nmkd-superscale	4x	清晰写实摄影	中高（4GB-6GB）	可下载	基于清晰摄影作品训练；可保留头发、线状纹理和枝叶细节。
realesrgan-anime-6b	4x	动漫 / 快速处理	低（1GB-2GB / CPU）	可下载	6-block 轻量级动漫模型，适用于快速处理。

下载其他模型

通过 CLI 或 download_model MCP 工具下载模型：

# Download 4x UltraSharp for portraits
upscalex download-model 4x-ultrasharp

# Download NMKD clean photo model
upscalex download-model 4x-nmkd-superscale

---

测试和验证

运行测试套件，验证模型分辨率计算、CLI 退出代码和实时 GPU 推理：

uv pip install -e ".[dev]"
uv run pytest -v

提交更改前，所有测试都必须通过。

---

贡献

欢迎为 UpscaleX 做出贡献。请阅读 CONTRIBUTING.md，了解编码规范、拉取请求流程和开发指南。

---

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。