MLX Swift LM（中文说明文档）

MLX Swift LM 是一个 Swift Package，用于在 MLX Swift 生态中构建和使用：

• 🧠 大语言模型（LLM）
• 👁️ 视觉语言模型（VLM）

项目地址：MLX Swift LM

---

⚠️ 重要说明

main 分支是 3.x 大版本升级，与 2.x 不兼容。

主要变化：

• tokenizer 与 downloader 完全拆分
• API 有破坏性更新（breaking changes）
• 需要参考升级指南：

👉 https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxlmcommon/upgrade

---

✨ 核心特性

MLX Swift LM 提供：

1. 模型加载能力

支持多种：

• tokenizer 集成
• 模型下载器
• HuggingFace 生态支持

---

2. 微调能力

• LoRA 微调（低成本训练）
• 全量模型微调
• 支持量化模型（4bit / 8bit）

---

3. 模型架构支持

• LLM（文本模型）
• VLM（图文模型）

---

📚 文档体系

🔹 MLXLMCommon

通用 API 层（LLM / VLM 统一接口）

👉 https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxlmcommon

---

🔹 MLXLLM

LLM 模型实现示例

👉 https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxllm

---

🔹 MLXVLM

视觉语言模型实现

👉 https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxvlm

---

🔹 MLXEmbedders

文本向量模型（embedding）

👉 https://swiftpackageindex.com/ml-explore/mlx-swift-lm/main/documentation/mlxembedders

---

🚀 使用方式

MLX Swift LM 支持 3 种集成方式：

---

📦 方式一：集成包（推荐）

Package.swift

.package(url: "https://github.com/ml-explore/mlx-swift-lm", .upToNextMajor(from: "3.31.3")),
.package(url: "https://github.com/DePasqualeOrg/swift-tokenizers-mlx", from: "0.1.0"),
.package(url: "https://github.com/DePasqualeOrg/swift-hf-api-mlx", from: "0.1.0"),

---

target 配置

.target(
name: "YourTargetName",
dependencies: [
.product(name: "MLXLLM", package: "mlx-swift-lm"),
.product(name: "MLXLMTokenizers", package: "swift-tokenizers-mlx"),
.product(name: "MLXLMHuggingFace", package: "swift-hf-api-mlx"),
])

---

🧩 方式二：Macros（兼容旧版）

使用 HuggingFace Swift 生态：

.package(url: "https://github.com/huggingface/swift-huggingface", upToNextMajor(from: "0.9.0")),
.package(url: "https://github.com/huggingface/swift-transformers", upToNextMajor(from: "1.3.0")),

---

target 配置

.target(
name: "YourTargetName",
dependencies: [
.product(name: "MLXLMCommon", package: "mlx-swift-lm"),
.product(name: "MLXLLM", package: "mlx-swift-lm"),
.product(name: "MLXHuggingFace", package: "mlx-swift-lm"),
.product(name: "HuggingFace", package: "swift-huggingface"),
.product(name: "Tokenizers", package: "swift-transformers"),
])

---

⚡ 快速开始

示例 1：使用 HuggingFace 模型

import MLXLLM
import MLXLMCommon
import MLXHuggingFace

import HuggingFace
import Tokenizers

let modelConfiguration = LLMRegistry.gemma3_1B_qat_4bit

let model = try await #huggingFaceLoadModelContainer(
configuration: modelConfiguration
)

let session = ChatSession(model)

print(try await session.respond(to: "请推荐旧金山两个景点"))
print(try await session.respond(to: "推荐一个好吃的餐厅"))

---

示例 2：加载本地模型

import MLXLLM
import MLXLMTokenizers

let modelDirectory = URL(filePath: "/path/to/model")

let container = try await loadModelContainer(
from: modelDirectory,
using: TokenizersLoader()
)

---

🧠 核心概念解释

1. ChatSession

用于管理对话上下文：

• 自动记忆上下文
• 多轮对话支持

---

2. ModelContainer

模型运行容器：

• 包含权重
• tokenizer
• 推理引擎

---

3. Tokenizer（重要变化）

3.x 版本：

tokenizer 不再内置，而是插件化

你必须自己选择：

• swift-tokenizers-mlx（推荐）
• HuggingFace tokenizer

---

4. Downloader（模型下载）

支持：

• HuggingFace 自动下载
• 本地模型加载
• 自定义 loader

---

🔥 3.x 最大变化总结

项目	2.x	3.x
tokenizer	内置	插件化
downloader	内置	可替换
API	一体化	模块化
灵活性	中等	很高
复杂度	低	中等

---

🧩 一句话总结

MLX Swift LM 3.x = 一个“模块化的 Swift 本地大模型运行框架”，所有能力都拆成插件，让你自由组合 tokenizer + 模型 + 下载器。