README.md

本教程旨在帮助用户基于苹果原生框架MLX-LM 部署和使用大模型，以便于充分利用 Apple M 系列芯片的性能进行本地推理。

🔧 环境配置

# 创建 Conda 虚拟环境
conda create -n mlx-lm python=3.11
conda activate mlx-lm
# 安装依赖
pip install -r requirements.txt

📁 项目结构

models_mlx/
├── run_app_gradio.py          # Gradio 交互式应用（模型下载 + 对话）
├── requirements.txt           # Python 依赖
├── configs/                   # 模型配置（JSON 格式，支持热加载）
│   └── model_info/
│       ├── mlx.json           #   MLX 量化模型列表
│       └── original.json      #   原始 HuggingFace 模型列表
├── modules/                   # 功能模块
│   └── download_model.py      #   模型下载模块（可独立运行）
├── models/                    # 下载的模型存放目录
├── notebooks/                 # Jupyter Notebook 教程
│   ├── Qwen3_MLX_部署与交互.ipynb
│   └── Qwen3_Transformers_部署与交互.ipynb
└── docs/                      # 文档
    └── MLX-LM_Intro.md        #   MLX 框架简介

📖 教程内容

理论部分

• MLX框架简介

Notebook 教程

Notebook	说明
Qwen3_MLX_部署与交互	使用 MLX 框架部署 Qwen3（Apple Silicon 推荐）
Qwen3_Transformers_部署与交互	使用 Transformers 框架部署 Qwen3（通用兼容）

Gradio 交互应用

集模型下载与对话为一体的 Web 界面，支持：

• 模型下载：按 公司 → 系列 → 模型 三级选择，自动检测本地是否已下载
• 模型对话：支持 MLX / Transformers 双框架，MLX 支持流式输出
• 参数调节：Temperature、Top-p、Max Tokens、思考模式
• 热加载：修改 configs/ 下的 JSON 配置后，刷新页面或点击刷新按钮即可生效

python run_app_gradio.py

命令行下载模型

也可以通过命令行交互式下载模型（无需启动 Gradio）：

python -m modules.download_model

🚀 支持模型

模型列表通过 configs/ 目录下的 JSON 文件配置。

公司	系列	模型列表
Alibaba	QwQ	QwQ-0.5B-4bit
Alibaba	Qwen1.5	Qwen1.5-0.5B-Chat-4bit Qwen1.5-1.8B-Chat-4bit Qwen1.5-MoE-A2.7B-4bit Qwen1.5-MoE-A2.7B-Chat-4bit
Alibaba	Qwen2	Qwen2-0.5B-Instruct-4bit Qwen2-1.5B-4bit Qwen2-1.5B-Instruct-4bit
Alibaba	Qwen2-Math	Qwen2-Math-1.5B-Instruct-4bit
Alibaba	Qwen2.5	Qwen2.5-0.5B-4bit Qwen2.5-0.5B-Instruct-4bit Qwen2.5-1.5B-4bit Qwen2.5-1.5B-Instruct-4bit Qwen2.5-3B-4bit Qwen2.5-3B-Instruct-4bit
Alibaba	Qwen2.5-Coder	Qwen2.5-Coder-0.5B-4bit Qwen2.5-Coder-0.5B-Instruct-4bit Qwen2.5-Coder-1.5B-4bit Qwen2.5-Coder-1.5B-Instruct-4bit Qwen2.5-Coder-3B-4bit Qwen2.5-Coder-3B-Instruct-4bit
Alibaba	Qwen2.5-Math	Qwen2.5-Math-1.5B-4bit Qwen2.5-Math-1.5B-Instruct-4bit
Alibaba	Qwen3	Qwen3-0.6B-4bit Qwen3-0.6B-Base-4bit Qwen3-1.7B-4bit
Alibaba	Qwen3.5	Qwen3.5-0.8B-4bit Qwen3.5-2B-4bit
DeepSeek	DeepSeek-R1	DeepSeek-R1-Distill-Qwen-1.5B-4bit
DeepSeek	DeepSeek-V3	-
Google	Gemma-2	gemma-2-2b-4bit gemma-2-2b-it-4bit gemma-2-2b-jpn-it-4bit gemma-2-baku-2b-it-4bit
Google	Gemma-3	gemma-3-1b-it-4bit gemma-3-1b-pt-4bit gemma-3-270m-4bit gemma-3-270m-it-4bit
Meta	Llama-3.1	-
Meta	Llama-3.2	Llama-3.2-1B-Instruct-4bit Llama-3.2-3B-Instruct-4bit
Meta	Llama-4	-
Microsoft	Phi-2	phi-2-super-4bit
Microsoft	Phi-4	-
Mistral	Mistral	Ministral-3-3B-Instruct-2512-4bit Ministral-3-3B-Reasoning-2512-4bit
Moonshot	Kimi	-

如需添加新模型，编辑 configs/model_info/mlx.json 或 configs/model_info/original.json 即可。