Nativ

本地 AI，专为你的 Mac 打造。

在一个 macOS 应用中聊天、提供服务、监控并连接 MLX 模型。

Nativ 是一个原生 macOS 工作区，用于在 Apple silicon 上本地运行 AI 模型。它内置了 [`mlx-vlm`](https://github.com/Blaizzy/mlx-vlm) 服务器，能在你的 Hugging Face 缓存中发现兼容的模型，并将整个体验封装在一个精致的 SwiftUI 应用中。 你可以将 Nativ 用作私人聊天应用、模型管理器、性能仪表板，或者为你常用的工具提供一个兼容 OpenAI 和 Anthropic 的本地推理服务器。 ## Nativ 能做什么 | 功能 | 你将获得 | |---|---| | **本地聊天与视觉** | 流式对话、图像附件、推理输出、响应指标以及持久化的聊天历史。 | | **模型库** | 发现已安装的 MLX 模型，在 Hugging Face 上浏览兼容的模型并下载，检查模型能力，切换模型或移除旧模型。 | | **性能分析** | 跟踪请求量、token 使用情况、首个 token 的生成时间、解码速度、模型性能以及最近的动态。 | | **本地 API** | 兼容 OpenAI 的聊天、Responses、图像、音频和模型 endpoint，以及 Anthropic 的 Messages endpoint。 | | **编程工具集成** | 配置并启动 Codex、Claude Code、Pi、Hermes 和 OpenCode，以使用 Nativ 提供的模型服务。 | | **开发者工作区** | 检查 runtime 详细信息，复制 endpoint URL，搜索和过滤实时服务器日志，并监控服务器健康状况。 | | **菜单栏控制** | 启动或停止服务器，更改已加载的模型，查看服务统计信息，并在不失去焦点的情况下打开主应用。 | | **高级推理控制** | 调整采样、思考预算、结构化输出、KV-cache 量化、前缀缓存和投机解码。 | 模型下载后，推理将在你的 Mac 上运行。模型下载和首次构建依赖项仍需要网络访问。 ## 即将推出 对专用的纯音频和纯图像生成模型的支持即将推出。 ## 工作原理 ``` flowchart LR A["Nativ · SwiftUI app"] --> B["NativServerKit"] B --> C["Bundled mlx-vlm server"] C --> D["MLX runtime"] D --> E["Local models · Apple unified memory"] F["Apps and coding agents"] -->|"localhost API"| C ``` `NativServerKit` 负责管理内嵌的 Python 发行版和服务器生命周期。该应用在此 runtime 的基础上增加了模型发现、聊天、分析、配置、集成、日志、菜单栏控制和软件更新等功能。 ## 系统要求 要运行此应用： - 一台搭载 Apple silicon 的 Mac。 - macOS 26 或更高版本。 - 足够的统一内存供你选择的模型使用。 如果要从源码构建，你还需要： - 安装了 macOS 26 SDK 的 Xcode。 - [`xcodegen`](https://github.com/yonaskolb/XcodeGen)。 - Python 3。 - 在首次组装或刷新内嵌的 Python bundle 时，需要访问 GitHub Releases 和 PyPI 的网络权限。 ## 开始使用 ### 下载发布版本 从 [GitHub Releases](https://github.com/Blaizzy/nativ/releases/latest) 下载最新的 DMG 文件，将 **Nativ** 拖入“应用程序”文件夹并启动。Nativ 使用 Sparkle 进行后续的应用内更新。 首次启动时： 1. 选择一个已安装的语言模型，或继续使用按需加载。 2. 可选择生成一个 API 密钥，以保护服务器的管理 endpoint。 3. 打开 **Models** 以下载或选择一个兼容的模型。 4. 开始聊天、查看分析数据，或连接支持的编程工具之一。 ### 从源码构建 ``` brew install xcodegen make xcode-generate make xcode-build open build/XcodeDerivedData/Build/Products/Debug/Nativ.app ``` 首次构建可能需要一些时间，因为 `NativServerKit` 会创建一个可重定位的 Python runtime，并将指定的 `mlx-vlm` 服务器依赖项安装到框架资源中。之后的构建会复用该 bundle，直到输入内容发生更改。 ## 将 Nativ 用作本地 API 服务器 默认情况下，该应用将其服务器暴露在 `http://127.0.0.1:8080`。开发者页面列出了所有可用的 endpoint，并允许你直接复制 URL。 例如，在选择了一个模型后： ``` curl http://127.0.0.1:8080/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "your-model-id", "messages": [{"role": "user", "content": "Why is the sky blue?"}], "stream": false }' ``` 如果你启用了服务器 API 密钥，请将其作为 Bearer token 一并发送： ``` -H 'Authorization: Bearer your-api-key' ``` 该服务器包含： - 兼容 OpenAI 的 `/v1/chat/completions`、`/v1/responses`、`/v1/models`、图像和音频路由。 - 兼容 Anthropic 的 `/v1/messages` 和 token 计数路由。 - `/health`、`/metrics`、缓存统计、缓存重置和模型卸载 endpoint。 ## 项目布局 ``` Sources/ ├── Nativ/ # SwiftUI application │ ├── Features/ │ │ ├── Chat/ │ │ ├── Dashboard/ │ │ ├── Developer/ │ │ ├── ImageGeneration/ │ │ ├── Integrations/ │ │ └── Models/ │ ├── Assets.xcassets/ │ ├── ModelProviderIcons/ │ └── Utilities/ └── NativServerKit/ # Embedded server and Swift clients PythonDistribution/ ├── Launcher/ # Relocatable server launcher ├── Requirements/ # Pinned Python dependencies └── Scripts/ # Bundle assembly and verification Configuration/ # App metadata and signing settings Design/ # Brand source files and README artwork scripts/ # Archive, signing, notarization, and release tools project.yml # XcodeGen project definition ``` ## 开发 ### 构建与冒烟测试 生成并构建 Xcode 项目： ``` make xcode-generate make xcode-build ``` 验证打包的可执行文件能否启动并打印 `mlx_vlm.server` 的帮助信息： ``` make xcode-smoke ``` 测试长时间运行的进程生命周期和 `/metrics` 的就绪状态： ``` make xcode-lifecycle-smoke ``` 生成一些真实请求，并比较前后的指标： ``` scripts/run_metrics_queries.py ``` 首次请求可能会因为模型的下载和加载而耗时较长。

专为 Apple silicon 上的快速、本地推理而构建。

标签：AI推理服务, macOS应用, MLX, SwiftUI, 兼容API, 本地大模型, 模型管理, 逆向工具