必须验证apple silicon或intel芯片型号、macos≥12.0版本及空闲内存≥12gb；安装python@3.11、libmetal并按路径选用ollama/llama.cpp/docker部署；通过vs code插件或curl接入，最后用api测试响应与metal加速标识确认功能正常。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
一、确认硬件与系统兼容性
Mac用户部署Core类工具（如代码助手、本地LLM服务等）前，必须验证硬件是否满足最低推理负载要求。Apple Silicon芯片对Metal加速支持直接影响模型加载速度与响应稳定性，而Intel Mac则依赖Rosetta 2转译，性能损耗显著。
1、打开“关于本机”，查看芯片型号：若显示“Apple M1”“M2”“M3”或“M4”，即支持原生Metal后端；若显示“Intel Core i5”或类似字样，则需启用Rosetta并接受约30%~40%的推理延迟上升。
2、检查macOS版本：执行sw_vers -productVersion命令，确保系统为macOS 12.0 Monterey或更高版本；低于此版本将无法加载最新版llama.cpp或Ollama的Metal GPU插件。
3、验证内存占用余量：运行top -o mem | head -20，确认空闲物理内存不低于12GB；7B参数模型在Metal下常驻内存约8–10GB，预留空间不足将触发频繁交换，导致服务卡顿或崩溃。
二、安装核心运行时环境
统一运行时是保障Core类工具稳定启动的基础。不同部署路径对底层依赖有差异化要求，需按实际选用方案精准安装，避免混用冲突版本。
1、通过Homebrew安装基础工具链：brew install python@3.11 cmake ninja wget；其中python@3.11为Ollama与llama.cpp官方推荐版本，使用其他Python版本可能导致模型加载失败。
2、安装Metal加速支持库：brew install libmetal；该库为llama.cpp编译时启用-DLLAMA_METAL=ON提供必要头文件与链接符号，缺失将退化至纯CPU模式，7B模型单次推理耗时从3500ms。
3、为Intel Mac额外启用Rosetta：前往“访达 → 应用程序 → 终端”，右键“显示简介”，勾选“使用Rosetta打开”；重启终端后执行arch应返回x86_64，表示转译已生效。
三、部署Core服务的三种可行路径
根据资源约束、可控性需求及交互方式偏好，可选择以下任一方式完成Core服务部署。各路径相互独立，不建议混合使用同一模型实例。
1、Ollama轻量级部署（适合快速验证）：
执行brew install ollama → 启动服务ollama serve → 拉取模型ollama pull codellama:7b → 测试调用curl http://localhost:11434/api/generate -d '{"model":"codellama:7b","prompt":"def fibonacci(n):"}'。
2、llama.cpp直编译部署（适合性能调优）：
克隆仓库git clone https://github.com/ggerganov/llama.cpp → 进入目录cd llama.cpp → 编译启用Metalmake clean && LLAMA_METAL=1 make → 下载GGUF格式模型wget https://huggingface.co/TheBloke/CodeLlama-7B-GGUF/resolve/main/codellama-7b.Q5_K_M.gguf → 启动服务./server -m codellama-7b.Q5_K_M.gguf -c 2048 --port 8080。
3、Docker容器化部署（适合隔离开发）：
安装Docker Desktop for Mac（需开启“Use the new Virtualization framework”选项）→ 创建docker-compose.yml，指定镜像ghcr.io/ollama/ollama:latest并映射端口11434:11434→ 执行docker-compose up -d → 推送模型至容器内docker exec -it ollama ollama pull codellama:7b。
四、接入本地模型的两种前端方式
Core服务运行后，需通过前端通道实现人机交互。接口协议一致，但客户端形态决定易用性与集成深度。
1、VS Code插件直连（推荐日常开发）：
安装扩展“CodeGPT”或“Continue.dev” → 在设置中定位“Model Provider”，选择“Ollama” → 填写API地址为http://localhost:11434 → 模型名称填入codellama:7b → 重启VS Code，状态栏出现“? Ollama Connected”即表示接入成功。
2、Curl命令行调试（推荐故障排查）：
构造JSON请求体并保存为req.json，内容为{"model":"codellama:7b","prompt":"write a Python function to sort a list in descending order","stream":false} → 执行curl http://localhost:11434/api/generate -H "Content-Type: application/json" -d @req.json → 观察返回中"response"字段是否含有效Python代码片段。
五、验证模型响应与基础功能
部署完成后必须执行最小闭环测试，确认从请求接收、模型推理到结果返回全链路无阻断。仅依赖服务进程存活状态不足以判断功能正常。
1、向Ollama API发送最简补全请求：curl -X POST http://localhost:11434/api/generate -H "Content-Type: application/json" -d '{"model":"codellama:7b","prompt":"def hello():\n return"}'。
2、检查返回体中是否存在"response"键且值非空字符串；若返回含"error"字段或HTTP状态码非200，说明模型未加载或Metal未启用。
3、观察终端日志中是否出现llm_load_tensors: loading model tensors及后续system_info: n_threads = 8 / 8 | CPU + Metal字样；缺少Metal标识即表示GPU加速未生效，需回溯第二步中libmetal安装与编译参数。
