Swama

英文 | 中文 | 日语

Swama 是一款纯 Swift 编写的高性能机器学习运行时，专为 macOS 设计，并基于 Apple 的 MLX 框架构建。它提供了一种强大且易于使用的本地 LLM（大型语言模型）和 VLM（视觉语言模型）推理解决方案。

✨ 特性

• 🚀 高性能: 基于 Apple MLX 框架，针对 Apple Silicon 进行优化
• 🔌 兼容 OpenAI API: 支持标准的 /v1/chat/completions、/v1/embeddings、/v1/audio/transcriptions 以及实验性的 /v1/audio/speech 端点，并支持工具调用
• 📱 菜单栏应用: 优雅的 macOS 原生菜单栏集成
• 💻 命令行工具: 完整的 CLI 支持，用于模型管理和推理
• 🖼️ 多模态支持: 同时支持文本和图像输入
• 🎤 本地音频转录: 内置 Whisper 语音识别功能（无需云端）
• 🔍 文本嵌入: 内置嵌入生成功能，适用于语义搜索和 RAG 应用
• 📦 智能模型管理: 自动下载、缓存和版本管理
• 🔄 流式响应: 支持实时流式文本生成
• 🌍 HuggingFace 集成: 直接从 HuggingFace Hub 下载模型

🏗️ 架构

Swama 采用模块化架构设计：

• SwamaKit: 包含所有业务逻辑的核心框架库
• Swama CLI: 提供完整模型管理和推理功能的命令行工具
• Swama.app: 带有图形界面和后台服务的 macOS 菜单栏应用

📋 系统要求

• macOS 15.0 或更高版本（Sequoia）
• Apple Silicon (M1/M2/M3/M4)
• Xcode 16.0+（用于编译）
• Swift 6.2+

🛠️ 安装

🍺 Homebrew（推荐）

brew install swama

📱 下载预编译应用

1. 下载最新版本

   • 访问 Releases
   • 下载最新版本中的 Swama.dmg

2. 安装应用

   • 双击 Swama.dmg 挂载磁盘映像
   • 将 Swama.app 拖到 Applications 文件夹
   • 从 Applications 或 Spotlight 启动 Swama

   注意: 首次启动时，macOS 可能会显示安全警告。如果出现这种情况：

   • 打开 系统偏好设置 > 安全性与隐私 > 通用
   • 点击 Swama 应用提示旁边的 “仍要打开”
   • 或右键点击应用并从上下文菜单中选择 “打开”

3. 安装 CLI 工具

   • 从菜单栏打开 Swama
   • 点击“安装命令行工具…”以将 swama 命令添加到你的 PATH 中

🔧 从源码构建（高级）

对于希望从源码构建的开发者：

# 克隆仓库
git clone https://github.com/Trans-N-ai/swama.git
cd swama

# 构建 CLI 工具
cd swama
swift build -c release
mv .build/release/swama .build/release/swama-bin

# 构建 macOS 应用（需要 Xcode）
cd ../swama-macos/Swama
xcodebuild -project Swama.xcodeproj -scheme Swama -configuration Release

🚀 快速入门

安装 Swama.app 后，你可以使用菜单栏应用或命令行：

1. 使用模型别名进行快速推理

# 使用简短别名代替完整模型名称 - 如需则自动下载！
swama run qwen3 "你好，AI"
swama run llama3.2 "给我讲个笑话"
swama run gemma3 "这张图片里有什么？" -i /path/to/image.jpg

# 传统方式（同样适用）
swama run mlx-community/Llama-3.2-1B-Instruct-4bit "你好，最近怎么样？"

# 列出已下载的模型
swama list

✨ 智能特性:

• 模型别名: 使用友好的名称如 qwen3、llama3.2、deepseek-r1、gpt-oss，而不用冗长的 URL
• 自动下载: 模型在首次使用时会自动下载，无需提前 pull
• 缓存管理: 已下载的模型会被缓存以供后续使用

2. 可用模型别名

语言模型 (LLM)

别名	完整模型名称	大小	描述
qwen3	mlx-community/Qwen3-8B-4bit	4.3 GB	通义千问3 8B（默认）
qwen3-1.7b	mlx-community/Qwen3-1.7B-4bit	938.4 MB	通义千问3 1.7B（轻量级）
qwen3-30b	mlx-community/Qwen3-30B-A3B-4bit	16.0 GB	通义千问3 30B（高容量）
qwen3-32b	mlx-community/Qwen3-32B-4bit	17.2 GB	通义千问3 32B（超大规模）
qwen3-235b	mlx-community/Qwen3-235B-A22B-4bit	123.2 GB	通义千问3 235B（万亿规模）
llama3.2	mlx-community/Llama-3.2-3B-Instruct-4bit	1.7 GB	Llama 3.2 3B（默认）
llama3.2-1b	mlx-community/Llama-3.2-1B-Instruct-4bit	876.3 MB	Llama 3.2 1B（最快）
deepseek-r1	mlx-community/DeepSeek-R1-0528-4bit	~32 GB	DeepSeek R1（推理模型）
deepseek-r1-8b	mlx-community/DeepSeek-R1-0528-Qwen3-8B-8bit	8.6 GB	基于Qwen3-8B的DeepSeek R1
qwen2.5	mlx-community/Qwen2.5-7B-Instruct-4bit	4.0 GB	通义千问2.5 7B
gpt-oss	lmstudio-community/gpt-oss-20b-MLX-8bit	~20 GB	GPT-OSS 20B（21B参数，3.6B活跃）
gpt-oss-120b	lmstudio-community/gpt-oss-120b-MLX-8bit	~120 GB	GPT-OSS 120B（117B参数，5.1B活跃）

视觉语言模型 (VLM)

别名	完整模型名称	大小	描述
qwen3.5	mlx-community/Qwen3.5-35B-A3B-4bit	~21 GB	通义千问3.5 35B-A3B（默认）
qwen3.5-0.8b	mlx-community/Qwen3.5-0.8B-4bit	~0.6 GB	通义千问3.5 0.8B
qwen3.5-2b	mlx-community/Qwen3.5-2B-4bit	~1.4 GB	通义千问3.5 2B
qwen3.5-4b	mlx-community/Qwen3.5-4B-4bit	~2.4 GB	通义千问3.5 4B
qwen3.5-9b	mlx-community/Qwen3.5-9B-4bit	~6.0 GB	通义千问3.5 9B
qwen3.5-27b	mlx-community/Qwen3.5-27B-4bit	~16 GB	通义千问3.5 27B
qwen3.5-35b-a3b	mlx-community/Qwen3.5-35B-A3B-4bit	~21 GB	通义千问3.5 35B-A3B
qwen3.5-122b-a10b	mlx-community/Qwen3.5-122B-A10B-4bit	~68 GB	通义千问3.5 122B-A10B
qwen3.5-397b-a17b	mlx-community/Qwen3.5-397B-A17B-4bit	~220 GB	通义千问3.5 397B-A17B
gemma3	mlx-community/gemma-3-4b-it-4bit	3.2 GB	Gemma 3 4B（默认VLM）
gemma3-27b	mlx-community/gemma-3-27b-it-4bit	15.7 GB	Gemma 3 27B（大型VLM）
qwen3-vl	mlx-community/Qwen3-VL-4B-Instruct-4bit	~4 GB	通义千问3-VL 4B（默认VLM）
qwen3-vl-2b	mlx-community/Qwen3-VL-2B-Instruct-4bit	~2 GB	通义千问3-VL 2B（轻量级）
qwen3-vl-8b	mlx-community/Qwen3-VL-8B-Instruct-4bit	~8 GB	通义千问3-VL 8B（平衡型）

音频模型（语音识别）

别名	完整模型名称	大小	描述
whisper-large	mlx-community/whisper-large-v3-4bit	1.6 GB	Whisper Large v3（最高精度）
whisper-medium	mlx-community/whisper-medium-4bit	791.1 MB	Whisper Medium（平衡型）
whisper-small	mlx-community/whisper-small-4bit	251.7 MB	Whisper Small（快速）
whisper-base	mlx-community/whisper-base-4bit	77.2 MB	Whisper Base（更快速）
whisper-tiny	mlx-community/whisper-tiny-4bit	40.1 MB	Whisper Tiny（最快）
funasr	mlx-community/Fun-ASR-Nano-2512-4bit	~200 MB	FunASR Nano（多语言）
funasr-mlt	mlx-community/Fun-ASR-MLT-Nano-2512-4bit	~200 MB	FunASR MLT（多语言转录）

文本到语音模型（实验性）

别名	完整模型名称	大小	描述
orpheus	mlx-community/orpheus-3b-0.1-ft-4bit	-	-
marvis	Marvis-AI/marvis-tts-100m-v0.2-MLX-6bit	-	-
chatterbox	mlx-community/Chatterbox-TTS-q4	-	-
chatterbox-turbo	mlx-community/Chatterbox-Turbo-TTS-q4	-	-
outetts	mlx-community/Llama-OuteTTS-1.0-1B-4bit	-	-
cosyvoice2	mlx-community/CosyVoice2-0.5B-4bit	-	-
cosyvoice3	mlx-community/Fun-CosyVoice3-0.5B-2512-4bit	-	-

3. 启动 API 服务

# 或不指定模型直接启动（可通过 API 切换）
swama serve --host 0.0.0.0 --port 28100

4. API 使用

🔌 OpenAI 兼容 API

Swama 提供完全兼容 OpenAI 的 API 端点，可与现有工具和集成无缝对接：

注意：/v1/audio/speech 为实验性功能。

# 获取可用模型
curl http://localhost:28100/v1/models

# 使用别名进行对话补全（如需会自动下载）
curl -X POST http://localhost:28100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [
      {"role": "user", "content": "你好！"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

# 使用 DeepSeek R1 进行流式响应
curl -X POST http://localhost:28100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1",
    "messages": [
      {"role": "user", "content": "请逐步解答：240 的 15% 是多少？"}
    ],
    "stream": true
  }'

# 生成文本嵌入
curl -X POST http://localhost:28100/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Hello world", "文本嵌入"],
    "model": "mlx-community/Qwen3-Embedding-0.6B-4bit-DWQ"
  }'

# 转录音频文件（本地处理）
curl -X POST http://localhost:28100/v1/audio/transcriptions \
  -F "file=@audio.wav" \
  -F "model=whisper-large" \
  -F "response_format=json"

# 文本到语音（TTS，实验性）
curl -X POST http://localhost:28100/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "orpheus",
    "input": "来自 Swama TTS 的问候",
    "voice": "tara",
    "response_format": "wav"
  }' --output speech.wav

# TTS 模型：orpheus、marvis、chatterbox、chatterbox-turbo、outetts、cosyvoice2、cosyvoice3
# 支持语音的模型：orpheus、marvis
# Orpheus 的声音选项：tara、leah、jess、leo、dan、mia、zac、zoe
# Marvis 的声音选项：conversational_a、conversational_b
# CosyVoice 在未提供参考音频时会使用缓存的默认参考音频

# 工具调用（函数调用）
curl -X POST http://localhost:28100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3",
    "messages": [{"role": "user", "content": "东京现在的天气如何？"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取当前天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "描述": "城市名称"}
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

# 多模态支持（视觉语言模型）
curl -X POST http://localhost:28100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma3",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "这张图片里有什么？"},
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ]
  }'

📚 命令参考

模型管理

# 下载模型（支持别名和完整名称）
swama pull qwen3                    # 使用别名
swama pull whisper-large            # 下载语音识别模型
swama pull mlx-community/Qwen3-8B-4bit  # 使用完整名称

# 列出本地模型及可用别名
swama list [--format json]

# 运行推理（若本地未找到模型则自动下载）
swama run qwen3 "您的提示在此"              # 使用别名 - 自动下载！
swama run deepseek-coder "编写一个 Python 函数"  # 另一个别名
swama run <完整模型名称> <提示> [选项]      # 使用完整名称

# 转录音频文件
swama transcribe audio.wav --model whisper-large --language en

服务器

# 启动 API 服务器
swama serve [--host HOST] [--port PORT]

模型别名

Swama 支持常用模型的便捷别名。您可以使用这些简短名称代替完整的模型 URL：

# 不同模型系列示例
swama run qwen3 "解释机器学习"           # Qwen3 8B
swama run llama3.2-1b "快速问题：什么是 AI？"  # Llama 3.2 1B（最快）
swama run deepseek-r1 "逐步思考：2+2*3"    # DeepSeek R1（推理能力）

选项

• --temperature <value>: 采样温度（0.0-2.0）
• --top-p <value>: 核采样参数（0.0-1.0）
• --max-tokens <number>: 最大生成标记数
• --repetition-penalty <value>: 重复惩罚因子

🔧 开发

依赖项

• swift-nio - 高性能网络框架
• swift-argument-parser - 命令行参数解析
• mlx-swift - Apple MLX Swift 绑定
• mlx-swift-lm - MLX Swift 语言模型
• mlx-swift-audio - MLX Swift 音频处理（Whisper、FunASR）

构建

# 开发构建
swift build

# 发布构建
swift build -c release

# 运行测试
swift test

# 生成 Xcode 项目
swift package generate-xcodeproj

🤝 贡献

我们欢迎社区贡献！请按照以下步骤操作：

1. 分支本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加一些很棒的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 遵循 Swift 编码风格指南
• 为新功能添加测试
• 更新相关文档
• 确保所有测试通过

📝 许可证

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

🙏 致谢

• Apple MLX 团队提供的优秀机器学习框架
• Swift NIO 提供的高性能网络支持
• 所有贡献者及社区成员

📞 支持

• 📝 问题追踪器
• 💬 讨论区

🗺️ 路线图

• 待办事项

---

Swama - 为 macOS 用户带来最佳本地 AI 体验 🚀

Swama 快速上手指南

Swama 是一款基于 Apple MLX 框架、使用纯 Swift 编写的高性能机器学习运行时，专为 macOS 和 Apple Silicon 芯片优化。它支持本地运行大语言模型（LLM）、视觉语言模型（VLM）及语音识别，并提供兼容 OpenAI 标准的 API 接口。

环境准备

在开始之前，请确保您的设备满足以下要求：

• 操作系统：macOS 15.0 (Sequoia) 或更高版本
• 硬件架构：Apple Silicon 芯片 (M1 / M2 / M3 / M4 系列)
• 开发工具（仅源码编译需要）：Xcode 16.0+ 和 Swift 6.2+
• 包管理器：推荐安装 Homebrew 以便快速部署

安装步骤

推荐使用 Homebrew 进行安装，也可选择下载图形化应用。

方式一：通过 Homebrew 安装（推荐）

打开终端，执行以下命令即可一键安装 CLI 工具：

brew install swama

方式二：安装 macOS 图形化应用

如果您更喜欢菜单栏应用或图形界面：

1. 下载安装包：访问 Releases 页面，下载最新的 Swama.dmg 文件。
2. 安装应用：双击挂载 DMG 文件，将 Swama.app 拖入 Applications 文件夹。
3. 首次运行：
   • 若在启动时遇到安全警告，请前往 系统设置 > 隐私与安全性 > 通用，点击“仍要打开”。
   • 或者右键点击应用图标选择“打开”。
4. 配置 CLI：启动菜单栏中的 Swama 应用，点击 "Install Command Line Tool…" 即可将 swama 命令添加到系统路径。

基本使用

安装完成后，您可以直接使用命令行进行模型推理，无需预先手动下载模型，Swama 会在首次运行时自动处理。

1. 快速推理（使用模型别名）

Swama 支持友好的模型别名，自动匹配并下载对应的量化模型。

文本对话：

# 使用 Qwen3 模型进行对话（自动下载）
swama run qwen3 "你好，请介绍一下你自己"

# 使用 Llama 3.2 模型
swama run llama3.2 "讲个笑话"

多模态识图：

# 使用 Gemma3 视觉模型分析图片
swama run gemma3 "这张图片里有什么？" -i /path/to/image.jpg

查看已下载模型：

swama list

常用模型别名参考：

• 轻量级：llama3.2-1b, qwen3-1.7b
• 均衡型：qwen3, llama3.2, gemma3 (默认 VLM)
• 高性能：deepseek-r1, qwen3-32b
• 语音识别：whisper-large, whisper-small

2. 启动本地 API 服务

Swama 提供完全兼容 OpenAI 格式的 API 端点，可轻松集成到现有应用中。

启动服务：

# 默认监听 localhost:28100
swama serve

# 指定主机和端口
swama serve --host 0.0.0.0 --port 28100

调用示例（curl）：

• 聊天补全：

  curl -X POST http://localhost:28100/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "qwen3",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  

• 流式输出：

  curl -X POST http://localhost:28100/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek-r1",
      "messages": [{"role": "user", "content": "逐步计算 15% of 240"}],
      "stream": true
    }'
  

• 语音转文字 (Whisper)：

  curl -X POST http://localhost:28100/v1/audio/transcriptions \
    -F "file=@audio.wav" \
    -F "model=whisper-large"
  

• 工具调用 (Function Calling)： 支持在请求中定义 tools 参数，模型可自动返回结构化函数调用指令。

• 多模态输入： 在 messages 中混合传入 text 和 image_url 即可实现识图对话。