前言最近在本机搭建 RAG / 向量检索相关能力时需要一个可以本地运行 Embedding 模型的服务。相比直接调用远程 APIOllama 的优势是安装简单、模型管理方便并且默认在本机提供 HTTP API适合开发调试和内网环境使用。本文记录一次在 Mac 上通过 Homebrew 安装 Ollama并拉取 bge-m3 向量模型的完整过程包括- 安装 Ollama- 使用 Homebrew Services 后台启动- 拉取 bge-m3 模型- 调用 Embedding 接口验证- 配置局域网 / 内网访问- 卸载与磁盘清理 本文环境macOS Homebrew。命令中的模型以 bge-m3 为例。一、安装 Ollama如果电脑上已经安装了 Homebrew可以直接执行brew install ollama安装完成后可以先检查版本ollama --version也可以查看 Ollama 是否能正常响应ollama --help二、启动 Ollama 服务Ollama 启动后会默认监听 11434 端口。使用 Homebrew 安装时可以通过 brew services 让它在后台常驻运行并支持开机自启brew services start ollama查看服务状态brew services list如果后面修改了配置或者想重启 Ollama可以执行brew services stop ollamabrew services start ollama也可以直接使用brew services restart ollama三、拉取 bge-m3 模型本文使用 bge-m3 作为 Embedding 模型ollama pull bge-m3bge-m3 是 BAAI 的多语言向量模型适合做文本向量化、语义检索、RAG 等场景。Ollama 模型页中也提供了对应的拉取命令和调用示例。拉取完成后可以查看本地已有模型ollama list如果看到类似下面的内容说明模型已经下载成功NAME ID SIZE MODIFIEDbge-m3:latest xxxxxxxx 1.2 GB ... 注意模型大小可能会随 Ollama 模型库更新而变化。之前记录中写的是约 570MB但当前 Ollama 模型页显示 bge-m3:latest 约为 1.2GB实际以 ollama pull 和 ollama list 输出为准。四、验证 Ollama 服务是否正常先验证 Ollama 自身服务curl http://localhost:11434/api/version正常情况下会返回版本信息例如{version: 0.x.x}也可以查看本机模型列表curl http://localhost:11434/api/tags五、调用 bge-m3 生成 EmbeddingOllama 原生 Embedding 接口是 /api/embedcurl http://localhost:11434/api/embed \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本}正常返回中会包含 embeddings 字段{model: bge-m3,embeddings: [[0.0123, -0.0456, ...]]}如果你的后端程序使用的是 OpenAI 兼容格式也可以调用 Ollama 的 OpenAI 兼容接口curl http://localhost:11434/v1/embeddings \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本}这里要注意两个接口的返回结构略有不同- Ollama 原生接口/api/embed- OpenAI 兼容接口/v1/embeddings如果后端代码已经按 OpenAI SDK 或 OpenAI API 格式封装一般使用 /v1/embeddings 更方便。六、允许局域网 / 内网访问 Ollama默认情况下Ollama 通常只面向本机访问。如果希望其他机器通过你的 Mac 访问 Ollama例如后端服务部署在另一台机器上就需要让 Ollama 监听 0.0.0.0:11434。Mac 上可以使用 launchctl setenv 设置环境变量launchctl setenv OLLAMA_HOST 0.0.0.0:11434然后重启 Ollama 服务brew services stop ollamabrew services start ollama或者brew services restart ollama验证端口是否监听lsof -iTCP:11434 -sTCP:LISTEN如果你当前 Mac 的内网 IP 是 xxx.xxx.xx.xx(xx代表你自己的ip地址)其他机器可以这样访问curl http://xxx.xxx.xx.xx:11434/v1/embeddings \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本} 注意地址应写成 http://xxx.xxx.xx.xx:11434/...不要写成 http://xxx.xxx.xx.xx/:11434/...。安全提醒如果只是本机开发不建议随意把 Ollama 暴露到公网。0.0.0.0:11434 代表监听所有网卡局域网、VPN 网段、Tailscale 网段等都有可能访问到。建议只在可信网络中使用并通过防火墙、VPN、反向代理鉴权等方式限制访问范围。七、后端配置示例如果你的后端项目中原来使用远程 Embedding API可以将配置切换成本机 Ollama。以 application.yaml 为例思路大致如下yamlrag:embedding:base-url: http://localhost:11434/v1model: bge-m3如果后端服务不在本机而是访问这台 Mac 上的 Ollama可以改成yamlrag:embedding:base-url: http://xxx.xxx.xx.xx:11434/v1model: bge-m3注(xx代表你自己的ip地址)修改后重启后端服务让配置生效。 具体字段名要根据自己的项目代码来定。这里重点是base-url 指向 Ollama 的 OpenAI 兼容地址模型名使用 bge-m3。八、常用命令汇总查看本地模型ollama list拉取模型ollama pull bge-m3删除指定模型ollama rm bge-m3查看 Ollama 版本curl http://localhost:11434/api/version查看 Ollama 模型列表接口curl http://localhost:11434/api/tags启动后台服务brew services start ollama停止后台服务brew services stop ollama重启后台服务brew services restart ollama九、卸载 Ollama如果后面不再需要本机 Ollama可以按下面步骤卸载。1. 停止 Ollama 服务brew services stop ollama2. 删除已下载模型如果只想删除 bge-m3ollama rm bge-m3如果已经准备彻底卸载也可以直接删除整个模型数据目录见第 4 步。3. 卸载 Ollamabrew uninstall ollama4. 删除模型数据目录Ollama 下载的模型默认会占用 ~/.ollama 目录空间。如果想彻底清理磁盘可以执行rm -rf ~/.ollama5. 清理环境变量如果之前设置过 OLLAMA_HOSTlaunchctl unsetenv OLLAMA_HOST卸载后如果需要切回远程 API将项目中的 application.yaml 或相关配置恢复为原来的远程 Embedding 地址然后重启后端服务即可。十、常见问题1. curl 提示连接失败先确认 Ollama 服务是否启动brew services list再检查端口lsof -iTCP:11434 -sTCP:LISTEN如果没有监听重启服务brew services restart ollama2. 其他机器访问不到检查三点- Mac 是否设置了 OLLAMA_HOST0.0.0.0:11434- Ollama 是否已经重启- 防火墙、VPN、Tailscale 或公司网络策略是否拦截了 11434 端口3. 模型下载很慢模型文件通常比较大下载速度取决于网络环境。可以先用ollama pull bge-m3如果中途失败重新执行同一条命令即可Ollama 一般会继续处理下载。4. /api/embed 和 /v1/embeddings 应该用哪个如果自己直接写脚本调用 Ollama用 /api/embed 就可以。如果项目原本兼容 OpenAI API或者使用 OpenAI SDK / 类 OpenAI 的配置项一般用 /v1/embeddings这样迁移成本更低。总结通过 Ollama 在 Mac 本机部署 bge-m3 后就可以很方便地获得本地 Embedding 服务。整体流程可以概括为brew install ollamabrew services start ollamaollama pull bge-m3curl http://localhost:11434/v1/embeddings \-H Content-Type: application/json \-d {model:bge-m3,input:测试文本}对于开发环境来说这种方式配置简单、调试方便也可以减少对远程 Embedding 服务的依赖。需要给其他机器访问时再通过 OLLAMA_HOST0.0.0.0:11434 开放监听即可但一定要注意访问范围和网络安全。参考资料- Ollama bge-m3 模型页https://ollama.com/library/bge-m3- Ollama API 文档https://github.com/ollama/ollama/blob/main/docs/api.md- Ollama OpenAI 兼容接口说明https://docs.ollama.com/openai
Mac本机安装Ollama并部署bge-m3向量模型：从安装到接口验证
前言最近在本机搭建 RAG / 向量检索相关能力时需要一个可以本地运行 Embedding 模型的服务。相比直接调用远程 APIOllama 的优势是安装简单、模型管理方便并且默认在本机提供 HTTP API适合开发调试和内网环境使用。本文记录一次在 Mac 上通过 Homebrew 安装 Ollama并拉取 bge-m3 向量模型的完整过程包括- 安装 Ollama- 使用 Homebrew Services 后台启动- 拉取 bge-m3 模型- 调用 Embedding 接口验证- 配置局域网 / 内网访问- 卸载与磁盘清理 本文环境macOS Homebrew。命令中的模型以 bge-m3 为例。一、安装 Ollama如果电脑上已经安装了 Homebrew可以直接执行brew install ollama安装完成后可以先检查版本ollama --version也可以查看 Ollama 是否能正常响应ollama --help二、启动 Ollama 服务Ollama 启动后会默认监听 11434 端口。使用 Homebrew 安装时可以通过 brew services 让它在后台常驻运行并支持开机自启brew services start ollama查看服务状态brew services list如果后面修改了配置或者想重启 Ollama可以执行brew services stop ollamabrew services start ollama也可以直接使用brew services restart ollama三、拉取 bge-m3 模型本文使用 bge-m3 作为 Embedding 模型ollama pull bge-m3bge-m3 是 BAAI 的多语言向量模型适合做文本向量化、语义检索、RAG 等场景。Ollama 模型页中也提供了对应的拉取命令和调用示例。拉取完成后可以查看本地已有模型ollama list如果看到类似下面的内容说明模型已经下载成功NAME ID SIZE MODIFIEDbge-m3:latest xxxxxxxx 1.2 GB ... 注意模型大小可能会随 Ollama 模型库更新而变化。之前记录中写的是约 570MB但当前 Ollama 模型页显示 bge-m3:latest 约为 1.2GB实际以 ollama pull 和 ollama list 输出为准。四、验证 Ollama 服务是否正常先验证 Ollama 自身服务curl http://localhost:11434/api/version正常情况下会返回版本信息例如{version: 0.x.x}也可以查看本机模型列表curl http://localhost:11434/api/tags五、调用 bge-m3 生成 EmbeddingOllama 原生 Embedding 接口是 /api/embedcurl http://localhost:11434/api/embed \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本}正常返回中会包含 embeddings 字段{model: bge-m3,embeddings: [[0.0123, -0.0456, ...]]}如果你的后端程序使用的是 OpenAI 兼容格式也可以调用 Ollama 的 OpenAI 兼容接口curl http://localhost:11434/v1/embeddings \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本}这里要注意两个接口的返回结构略有不同- Ollama 原生接口/api/embed- OpenAI 兼容接口/v1/embeddings如果后端代码已经按 OpenAI SDK 或 OpenAI API 格式封装一般使用 /v1/embeddings 更方便。六、允许局域网 / 内网访问 Ollama默认情况下Ollama 通常只面向本机访问。如果希望其他机器通过你的 Mac 访问 Ollama例如后端服务部署在另一台机器上就需要让 Ollama 监听 0.0.0.0:11434。Mac 上可以使用 launchctl setenv 设置环境变量launchctl setenv OLLAMA_HOST 0.0.0.0:11434然后重启 Ollama 服务brew services stop ollamabrew services start ollama或者brew services restart ollama验证端口是否监听lsof -iTCP:11434 -sTCP:LISTEN如果你当前 Mac 的内网 IP 是 xxx.xxx.xx.xx(xx代表你自己的ip地址)其他机器可以这样访问curl http://xxx.xxx.xx.xx:11434/v1/embeddings \-H Content-Type: application/json \-d {model: bge-m3,input: 测试文本} 注意地址应写成 http://xxx.xxx.xx.xx:11434/...不要写成 http://xxx.xxx.xx.xx/:11434/...。安全提醒如果只是本机开发不建议随意把 Ollama 暴露到公网。0.0.0.0:11434 代表监听所有网卡局域网、VPN 网段、Tailscale 网段等都有可能访问到。建议只在可信网络中使用并通过防火墙、VPN、反向代理鉴权等方式限制访问范围。七、后端配置示例如果你的后端项目中原来使用远程 Embedding API可以将配置切换成本机 Ollama。以 application.yaml 为例思路大致如下yamlrag:embedding:base-url: http://localhost:11434/v1model: bge-m3如果后端服务不在本机而是访问这台 Mac 上的 Ollama可以改成yamlrag:embedding:base-url: http://xxx.xxx.xx.xx:11434/v1model: bge-m3注(xx代表你自己的ip地址)修改后重启后端服务让配置生效。 具体字段名要根据自己的项目代码来定。这里重点是base-url 指向 Ollama 的 OpenAI 兼容地址模型名使用 bge-m3。八、常用命令汇总查看本地模型ollama list拉取模型ollama pull bge-m3删除指定模型ollama rm bge-m3查看 Ollama 版本curl http://localhost:11434/api/version查看 Ollama 模型列表接口curl http://localhost:11434/api/tags启动后台服务brew services start ollama停止后台服务brew services stop ollama重启后台服务brew services restart ollama九、卸载 Ollama如果后面不再需要本机 Ollama可以按下面步骤卸载。1. 停止 Ollama 服务brew services stop ollama2. 删除已下载模型如果只想删除 bge-m3ollama rm bge-m3如果已经准备彻底卸载也可以直接删除整个模型数据目录见第 4 步。3. 卸载 Ollamabrew uninstall ollama4. 删除模型数据目录Ollama 下载的模型默认会占用 ~/.ollama 目录空间。如果想彻底清理磁盘可以执行rm -rf ~/.ollama5. 清理环境变量如果之前设置过 OLLAMA_HOSTlaunchctl unsetenv OLLAMA_HOST卸载后如果需要切回远程 API将项目中的 application.yaml 或相关配置恢复为原来的远程 Embedding 地址然后重启后端服务即可。十、常见问题1. curl 提示连接失败先确认 Ollama 服务是否启动brew services list再检查端口lsof -iTCP:11434 -sTCP:LISTEN如果没有监听重启服务brew services restart ollama2. 其他机器访问不到检查三点- Mac 是否设置了 OLLAMA_HOST0.0.0.0:11434- Ollama 是否已经重启- 防火墙、VPN、Tailscale 或公司网络策略是否拦截了 11434 端口3. 模型下载很慢模型文件通常比较大下载速度取决于网络环境。可以先用ollama pull bge-m3如果中途失败重新执行同一条命令即可Ollama 一般会继续处理下载。4. /api/embed 和 /v1/embeddings 应该用哪个如果自己直接写脚本调用 Ollama用 /api/embed 就可以。如果项目原本兼容 OpenAI API或者使用 OpenAI SDK / 类 OpenAI 的配置项一般用 /v1/embeddings这样迁移成本更低。总结通过 Ollama 在 Mac 本机部署 bge-m3 后就可以很方便地获得本地 Embedding 服务。整体流程可以概括为brew install ollamabrew services start ollamaollama pull bge-m3curl http://localhost:11434/v1/embeddings \-H Content-Type: application/json \-d {model:bge-m3,input:测试文本}对于开发环境来说这种方式配置简单、调试方便也可以减少对远程 Embedding 服务的依赖。需要给其他机器访问时再通过 OLLAMA_HOST0.0.0.0:11434 开放监听即可但一定要注意访问范围和网络安全。参考资料- Ollama bge-m3 模型页https://ollama.com/library/bge-m3- Ollama API 文档https://github.com/ollama/ollama/blob/main/docs/api.md- Ollama OpenAI 兼容接口说明https://docs.ollama.com/openai
