macOS12 (Intel)本地通过编译启动Qwen3模型

macOS12 Intel 完整流程总结：编译 llama.cpp → 下载GGUF → 启动 Qwen3-4B-Instruct-2507-Q4_K_M.gguf

环境：macOS 12 Monterey，Intel CPU；不启用Metal GPU，全程CPU推理；最终使用 llama-server 提供 OpenAI 兼容接口，供 agentscope-java 调用

一、前置依赖安装（只需要执行一次）

1. 安装 Xcode CommandLineTools（编译必备）

xcode-select --install

2. 拉取 llama.cpp 源码

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

二、CMake 编译（Intel Mac，关闭Metal，不编译WebUI，避免404）

因为是Intel + macOS12，Metal不适用；本次只编译核心 llama-cli / llama-server，不打包前端网页（网页会404，但是API接口正常，正好给agentscope-java调用）

# 清空旧构建目录
rm -rf build
# CMake配置：关闭Metal，Release模式
cmake -B build -DGGML_METAL=OFF -DCMAKE_BUILD_TYPE=Release
# 编译，使用全部CPU核心
cmake --build build -j$(sysctl -n hw.ncpu)

编译完成后，可执行文件路径：llama.cpp/build/bin/

• llama-cli：命令行交互
• llama-server：OpenAI兼容API服务（重点，给agentscope-java用）

三、下载模型 Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf

模型仓库：bartowski/Qwen_Qwen3-4B-Instruct-2507-GGUF
✅ Q4_K_M：4bit量化，兼顾内存/效果，适合8G内存Intel Mac

两种下载方式任选其一：

方式1：浏览器国内镜像（推荐，避开python各种cli坑）

链接：https://hf-mirror.com/bartowski/Qwen_Qwen3-4B-Instruct-2507-GGUF/blob/main/Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf

1. 页面点 Download
2. 下载完成，把 Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf 复制到 llama.cpp/build/bin/

方式2：python脚本下载（之前用的方案）

cd build/bin
cat > download.py <<'EOF'
from huggingface_hub import hf_hub_download
import os
out_dir = os.path.expanduser(".")
fp = hf_hub_download(
    repo_id="bartowski/Qwen_Qwen3-4B-Instruct-2507-GGUF",
    filename="Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf",
    local_dir=out_dir,
    local_dir_use_symlinks=False
)
print("下载完成：", fp)
EOF
python3 download.py

四、启动方式二选一

目录：cd ~/llama.cpp/build/bin

方式A：llama-cli 命令行聊天（验证模型能否加载）

./llama-cli -m Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf -c 2048 -ngl 0 -t $(sysctl -n hw.ncpu)

• -ngl 0：关闭GPU，纯CPU
• -c 2048：上下文窗口大小
• -t：线程数等于CPU核心>

出现 > 提示符代表加载成功，可以直接对话。

方式B：llama-server（重点，给agentscope-java调用 OpenAI兼容接口）

./llama-server -m Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf -c 2048

✅ 成功标志日志：

llama_server: model loaded
llama_server: listening on http://127.0.0.1:8080

⚠️ 浏览器访问 http://127.0.0.1:8080 会返回404：缺少WebUI前端资源，属于正常现象，不影响API调用

五、验证API连通性（给agentscope-java调用前必须测试）

新开终端，保持 llama-server 运行，执行curl：

curl [http://127.0.0.1:8080/v1/chat/completions](http://127.0.0.1:8080/v1/chat/completions) \
-H "Content-Type: application/json" \
-H "Authorization: Bearer dummy" \
-d '{
"messages": [{"role":"user","content":"你好，介绍下你自己"}]
}'

返回JSON带模型回答，代表接口正常。

API基础地址：http://127.0.0.1:8080/v1

六、接入 agentscope-java

使用 OpenAIChatModel，baseUrl填 http://127.0.0.1:8080/v1，apiKey随便填dummy。

package com.example.agent.demo;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.extensions.model.openai.OpenAIChatModel;
import io.agentscope.extensions.model.openai.formatter.OpenAIChatFormatter;


public class ReActLocalDemo {
    public static void main(String[] args) {
        OpenAIChatModel model = OpenAIChatModel.builder()
                .apiKey("dummy")
                .modelName("qwen3-4b")
                .baseUrl("http://127.0.0.1:8080/v1")
                .stream(false)
                .formatter(new OpenAIChatFormatter())
                .build();

        ReActAgent agent = ReActAgent.builder()
                .name("react-agent")
                .model(model)
                .sysPrompt("你是本地智能助手，可以调用工具。")
                .build();

        String resp = agent.call("你好，帮我写一首山水诗" , RuntimeContext.empty())
                .block()
                .getTextContent();
        System.out.println(resp);
    }
}

七、通过ChatBox连接本地模型聊天

chatbox下载链接：https://chatboxai.app/zh/install?download=darwin-x86_64
设置chatbox可以选择本地模型


使用chatbox和本地模型进行聊天

八、重要注意事项（macOS12 Intel）

1. 内存：8G物理内存必须关闭浏览器、大型软件，否则大量swap，推理极慢（速度约1~3 token/s）
2. 警告 no usable GPU found、control-looking token: 128247 '</s>'：均可忽略，不影响功能
3. 接口地址末尾必须带 /v1，少写会404；浏览器根路径404是缺少前端，API不受影响
4. 关闭服务：在llama-server终端按 Ctrl+C
5. 推理慢是Intel老CPU正常现象，属于硬件限制

九、故障速查清单

1. 编译失败：确认xcode命令行工具已装好，源码完整
2. 模型加载失败：GGUF文件名不要写错，文件放到build/bin目录
3. curl返回404：检查baseUrl是否带/v1，确认llama-server正在运行
4. 超时：Java代码增加读写超时，CPU推理耗时很长