《C++ 项目:手写大模型接入 SDK》本地 Ollama 部署与适配

🔥小叶-duck:个人主页
❄️个人专栏:《Data-Structure-Learning》《C++入门到进阶&自我学习过程记录》
《Linux系统从入门到实践》《Linux网络从入门到实践》
《Qt 方寸极境》 《MySQL》
✨未择之路,不须回头
已择之路,纵是荆棘遍野,亦作花海遨游
目录
5.3.1 Expose Ollama to the network(网络暴露)
前言
在前面的章节中,我们已经完成了多款云端大模型 Provider 的实现,基于统一的抽象接口,对接了 DeepSeek、ChatGPT、Gemini 等厂商的云端 API,熟悉了 HTTP 请求构造、SSE 流式解析、不同厂商接口差异适配等开发要点。
云端方案虽然上手简单、不用关心硬件算力,但也存在网络依赖、数据外传、调用成本等局限。而本地私有化部署的大模型,可以把推理过程完全放在本机或者内网服务器,数据不出内网,更适合隐私敏感、低延迟需求的场景。Ollama 作为目前主流的本地大模型运行工具,屏蔽了底层推理引擎、模型打包、服务启停的复杂细节,对外提供了兼容 OpenAI 风格的 HTTP 接口,天然可以接入我们这套 SDK 框架。
本章我们将从云端与本地部署的对比开始,循序渐进介绍本地大模型的选型、原生部署思路,重点讲解 Ollama 在 Ubuntu、Windows 两大平台下的安装、命令、存储结构与环境变量配置。我们先吃透 Ollama 本身的服务机制,为后续在 SDK 中新增 OllamaProvider、完成本地模型的全量与流式接入做好铺垫。
一、云端接入与本地部署对比
在前面章节,我们已经完成了 DeepSeek、ChatGPT、Gemini 等云端大模型的 SDK 接入,全部是基于厂商开放的远程 API 进行调用。
但除了云端 API 方案之外,本地私有化部署也是大模型落地非常主流的路线。我们先对比两种方案的适用场景、优缺点,理清选型逻辑。
1.1 云端大模型接入方案
云端方案,就是直接调用厂商托管在远端服务器上的大模型服务,通过网络 API 发送请求,由厂商算力完成推理并返回结果。
1.1.1 云端方案优势
- 效果更强:云端依托大规模集群算力,可运行超大参数量模型,输出质量普遍优于本地能承载的模型。
- 开箱即用:不需要下载模型、配置运行环境,注册账号、获取 API Key 之后就可以直接调用。
- 自动迭代升级:模型由厂商统一维护,持续优化权重、修复问题,使用者不需要关心版本更新。
- 生态完善:很多云端服务附带插件、联网搜索、多模态等附加能力,拓展能力丰富。
1.1.2 云端方案短板
- 隐私合规风险:所有对话数据、输入内容都会上传到厂商远端服务器。医疗、金融、政务、企业代码这类敏感数据,会存在数据泄露风险,部分行业法规直接禁止数据外传。
- 调用成本压力:按 Token 计费,单次调用单价看着不高,但高频、大规模业务场景下,长期调用开销会持续累积。
- 强依赖网络:必须依托公网,无网环境无法使用;同时会存在网络延迟、访问受限、高峰期限流、接口不可用等问题。
- 可控能力有限:使用者很难深度干预模型内部,不方便自定义推理参数、微调模型、定制输出格式。
1.2 本地私有化部署方案
本地部署(私有化部署)指将开源大模型下载到自有服务器、本地主机或者私有云环境中,在本地硬件上完成推理,不依赖第三方厂商的远程推理服务,使用者掌握模型全生命周期和调用链路。
1.2.1 本地部署核心优势
- 隐私安全可控:全部推理流程在本地环境闭环,数据不会外传,满足强监管行业的数据合规要求。
- 零边际调用成本:模型下载完成之后,反复调用不再产生 API 计费,高频使用场景成本优势明显。
- 支持离线运行:不需要公网,保密单位、边缘设备、无网偏远区域都可以正常提供推理服务。
- 高度灵活定制:可以自由切换模型版本、调整全部推理参数,还能加载微调后的专属模型,深度贴合业务的输出规范。
1.2.2 本地部署固有缺陷
- 硬件门槛高:对显卡显存、整机内存、存储都有硬性要求,大参数量模型需要专业的 GPU 集群支撑。
- 推理效果受限:受限于本机硬件算力,大多数普通设备只能运行中小参数量模型,回答质量对比云端超大模型存在差距。
- 前期投入高昂:模型文件体积巨大,下载、存储成本高;高性能显卡采购、服务器搭建都需要一次性高额投入。
1.3 DeepSeek-R1 本地部署硬件参考规格
以 DeepSeek-R1 系列 FP16 全量精度版本为例,不同参数量模型对应的硬件门槛差异很大:
| 模型名称 | 文件大小 | 最低显卡配置 | 内存配置 | 最低 GPU 显存 | 价格预算区间 |
|---|---|---|---|---|---|
| DeepSeek-R1-1.5B | 3GB | RTX 3050 8GB | 8GB | ≥4GB | 3000~5000 元 |
| DeepSeek-R1-7B | 5GB | RTX 4060 16GB | 16~32GB | ≥8GB | 7000~10000 元 |
| DeepSeek-R1-14B | 15GB | RTX 4070 Ti SUPER 16GB | 32GB | ≥16GB | 1.8 万~2.8 万元 |
| DeepSeek-R1-32B | 30GB | 双路 RTX 4070 Ti SUPER 16GB | 64GB | ≥24GB | 6 万~9 万元 |
| DeepSeek-R1-70B | 70GB | 4 路 RTX 5090D 24GB | 128GB | ≥80GB | 25 万~45 万元 |
| DeepSeek-R1-671B | 200GB 以上 | 8 路 A100 80GB | 512GB 以上 | ≥256GB | 120 万元以上 |
1.4 本地大模型通用实施流程
想要落地本地大模型,一般遵循以下五步流程:
- 硬件评估准备:清点现有 GPU、CPU、内存、硬盘资源,判断硬件上限能够承载多大参数规模的模型。
- 模型选型匹配:结合硬件能力和业务需求,挑选合适的开源模型。
- 部署工具选型:选择本地模型管理运行工具,主流方案包含 Ollama、LM Studio;本项目后续选用 Ollama 进行开发。
- 模型下载加载:通过部署工具完成模型拉取、校验、本地加载,启动本地推理服务。
- 业务集成交互:通过本地开放的 API 接口,接入我们之前开发的这套 C++ SDK,完成业务调用。

二、无第三方封装工具:本地大模型原生搭建方案
在前面我们提到可以使用 Ollama 这类第三方工具快速拉起本地大模型服务,而如果抛开这类封装工具,想要从零原生搭建本地大模型,就要拆分成模型获取、推理引擎部署、推理交互代码开发这三个核心环节。
3.1 模型资源获取
3.1.1 开源模型仓库
我们可以从主流开源模型平台下载模型文件:
- Hugging Face Hub:全球主流开源模型生态平台,收录海量开源模型、数据集,地址:https://huggingface.co/
- ModelScope(魔搭):国内阿里达摩院维护的开源模型社区,国内访问更友好,地址:模型库 - ModelScope 魔搭社区
- 模型官方仓库:模型研发团队的官方发布渠道,一般会放出原版权重、配套说明文档。
3.1.2 模型选型原则
选型时不能只看模型效果,需要结合自身业务需求,同时对照硬件条件,根据显卡显存、内存、算力,挑选参数规模、量化等级匹配的模型。
3.1.3 模型文件的本质
很多人会有一个误区:下载完模型就可以在本地直接运行起来了。
实际上模型并不是可执行程序,下载得到的是一组文件集合,里面包含权重分片文件、配置文件、词表文件、元信息清单等。 以 Ollama 存储结构举例,模型文件主要分为两类:
- blobs:存放二进制的模型权重分片
- manifests:存放模型元数据、版本清单信息

3.2 推理引擎部署
仅仅拿到模型权重文件还无法完成推理,还需要配套的推理引擎,它是大模型的执行载体,也就是模型的运行器。
推理引擎承担这些核心工作:加载模型权重、对输入文本做预处理、Token 编码、完成张量数学运算、逐 Token 生成输出文本、结果解码。
主流开源推理引擎有两种:
- llama.cpp:纯 C/C++ 实现的轻量推理引擎,支持 CPU、GPU 混合推理,兼容大量量化格式,资源开销低,很适合本地、端侧部署。
- Hugging Face Transformers:Python 生态里最常用的模型框架,提供统一的加载、推理接口,适配绝大多数开源模型,适合调试、原型开发。
3.3 推理交互代码实现
引擎部署完成之后,还需要自己编写交互代码,语言可以选择 Python 或者 C++。
完整的执行链路:加载模型权重 → 输入文本Token化编码 → 前向张量推理计算 → 输出Token解码 → 拼接返回文本
补充说明:这种原生搭建方式门槛更高,需要理解模型底层原理、张量运算、框架 API,开发、调试、适配的成本远高于 Ollama 这类封装工具,适合想要深入理解底层运行逻辑的开发者。
三、Ollama 介绍
3.1 核心定位与价值
Ollama 是一款开源的本地大语言模型管理与服务工具,官方标语:Get up and running with large language models,也就是快速启动并运行大语言模型。
它的核心价值,就是把原生本地部署里繁琐的模型下载、权重管理、推理调度、服务接口封装等整套流程打包简化,把复杂的底层操作变成简单的命令行操作,让普通用户也能在消费级 PC 硬件上跑起开源大模型。
它具备几项核心能力:模型下载与版本管理、本地推理调度、对外提供 HTTP API 服务、多模型快速切换。
3.2 核心技术特性
- 开源免费:Ollama 本体代码开源可审计,配套支持的开源模型也可以免费使用,没有额外付费门槛。
- 部署简单:避开了原生搭建时复杂的环境依赖、推理引擎编译配置,只依靠少量命令,就能完成安装、拉取模型、启动推理。
- 跨平台适配:原生支持 macOS、Linux、Windows 三大桌面系统,同时提供官方 Docker 镜像,适配容器化部署场景。
- 丰富的模型生态:内置大量主流开源模型,包含 DeepSeek-R1、Llama3.3、Gemma2、Qwen2 等,支持一键拉取、快速切换不同模型版本。
- Modelfile 标准化打包:引入 Modelfile 机制,把模型权重、运行参数、系统提示词等全部配置打包成一个标准化单元,方便模型版本管理、分享和复现。
- 支持工具调用(Function Calling):对 Llama 3.1 这类支持函数调用的模型,Ollama 可以承载工具调用能力,让大模型完成更复杂的任务编排。
- 硬件自适应调度:启动时自动识别本机硬件资源,优先使用 GPU 加速推理,提升生成速度;没有可用 GPU 时,自动降级使用 CPU 完成推理。
- 本地隐私安全:所有对话数据、计算过程都在本机完成,不会自动向外发送数据,适合对数据隐私有要求的场景。
- 活跃社区生态:依托 GitHub、Discord 社区,持续迭代功能,用户可以查阅文档、交流问题、分享自定义模型。
四、Ubuntu 环境下 Ollama 安装与运维
4.1 安装部署
4.1.1 一键脚本安装
官方提供标准化一键安装脚本,在终端执行下面这条命令,即可自动化完成 Ollama 的全部安装流程:
curl -fsSL https://ollama.com/install.sh | sh
脚本执行完成后,Ollama 默认会以守护进程的形式自动在后台启动服务。
4.1.2 版本校验
安装结束后,执行版本查看命令,确认安装成功并查看当前版本:
ollama -v
示例输出:ollama version is 0.11.8
4.2 服务运行机制
4.2.1 进程管理模式
- 前台启动:执行
ollama server启动前台进程,一旦关闭终端窗口,进程就会终止,只适合临时调试、排错使用。 - 后台服务管理(生产推荐):正式环境推荐使用
systemctl管理服务,服务常驻后台,关闭终端也不会停止。
sudo systemctl start ollama # 启动服务
sudo systemctl stop ollama # 停止服务
sudo systemctl restart ollama # 重启服务
sudo systemctl status ollama # 查看服务状态
查看 Ollama 进程运行情况:
ps -ef | grep ollama
ollama 1861551 1 0 03:32 ? 00:00:09 /usr/local/bin/ollama serve
bit 1994271 1852472 0 08:35 pts/3 00:00:00 grep --color=auto ollama
4.2.2 端口与监听规则
Ollama 默认监听本机回环地址 127.0.0.1 的 11434 端口,本地 API 统一访问端点:http://127.0.0.1:11434。 使用 netstat 校验端口监听状态:
sudo netstat -tuln -p | grep 11434
tcp 0 0 127.0.0.1:11434 0.0.0.0:* LISTEN 1861551/ollama
127.0.0.1 是本机环回地址,它的作用范围是当前运行 Ollama 的这一台主机,不能跨主机互通:
- 如果 Ollama 部署在 Windows 主机:只有 Windows 本机内的程序可以直接用
127.0.0.1:11434访问;同局域网下的 Ubuntu 或者其他设备,不能使用127.0.0.1访问,需要开启 Ollama 局域网访问权限,填写 Windows 主机的局域网 IP。 - 如果 Ollama 部署在 Ubuntu 主机:Windows 主机同样不能用
127.0.0.1:11434去连接,必须使用 Ubuntu 机器的局域网 IP 进行访问。
默认配置下,仅本机能够访问这个接口;如果需要局域网其他设备调用,需要修改监听地址。
4.3 核心命令集
提示:所有模型相关操作,都要求填写完整模型标识,格式为
模型名:标签,例如deepseek-r1:1.5b。
4.3.1 模型生命周期管理
ollama pull <模型名>:从 Ollama 官方模型仓库拉取模型到本地存储ollama list:列出本机已经下载好的全部模型,展示模型 ID、占用体积、修改时间ollama rm <模型名>:删除本地指定模型以及关联清单文件ollama show <模型名>:查看模型的元信息、运行配置参数
4.3.2 运行与会话管理
ollama run <模型名>:加载并启动模型,进入交互式对话终端;本地无该模型时,会自动发起拉取ollama ps:列出当前正在运行的模型进程ollama stop <模型名>:停止正在运行的模型,释放内存、显存资源ollama help:查看全部命令的帮助说明-v / --version:查看 Ollama 版本信息-h / --help:查看命令帮助
4.3.3 交互式终端内置指令
进入 ollama run 对话终端之后,支持下面这些内置控制指令:
/show:查看当前会话变量、模型元信息/load <模型>:在对话终端内直接切换加载别的模型/save <模型>:保存当前的会话状态/clear:清空当前对话上下文/bye:退出交互式对话终端/?:查看终端内全部快捷指令帮助
4.4 本地模型存储结构
Ollama 的模型文件默认存放在 ~/.ollama/ 目录,分为两个核心子目录,采用镜像分层的设计思路。
bit@bit08:~/.ollama$ sudo ls -l /usr/share/ollama/.ollama/models
total 8
drwxr-xr-x 2 ollama ollama 4096 Sep 2 04:30 blobs
drwxr-xr-x 3 ollama ollama 4096 Sep 2 04:30 manifests
4.4.1 blobs 目录
存放模型真正的权重二进制分片文件;文件名采用 sha256-<哈希值> 命名,依靠哈希校验保证文件唯一、实现跨模型去重。模型参数规模越大,对应的 blob 文件占用磁盘空间也就越大。
4.4.2 manifests 目录
存放模型的清单描述文件,是标准 JSON 格式。
清单内部包含模型元数据(名称、版本、描述)、分层依赖关系、运行参数配置;同时记录每一层文件(权重、提示词模板、许可证、参数)的哈希值与文件大小。
{
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"digest": "sha256:a85fe2a2e58e2426116d3686ddc1a6ea58640c1e684069976aa730be6c1fa01",
"size": 487
},
"layers": [
{
"mediaType": "application/vnd.ollama.image.model",
"digest": "sha256:aabd4debf8c8f08881923f2c25fc0fdeed24435271c2b3e92c4af36704040dbc",
"size": 1117320512
},
{
"mediaType": "application/vnd.ollama.image.template",
"digest": "sha256:c5ad996bda6eed4df6e3b605a9869647624851ac248209d22fd5e2c0cc1121d3",
"size": 556
},
{
"mediaType": "application/vnd.ollama.image.license",
"digest": "sha256:6e4c38e1172f42fdbff13edf9a7a017679fb82b0fde415a3e8b3c31c6ed4a4e4",
"size": 1065
},
{
"mediaType": "application/vnd.ollama.image.params",
"digest": "sha256:f4d24e9138dd4603380add165d2b0d970bef471fac194b436ebd50e6147c6588",
"size": 148
}
]
}
4.4.3 模型加载流程
执行 ollama run <模型名> 时,内部执行逻辑:
- 检索 manifests 目录,匹配目标模型对应的清单文件
- 解析清单里面每一层对应的哈希值
- 根据哈希值,在 blobs 目录定位到对应的权重等数据文件
- 将模型权重加载进内存,启动推理,对外提供交互能力
五、Windows 环境下 Ollama 安装与运维
5.1 安装部署
5.1.1 系统要求
仅支持 Windows 10 及以上版本的操作系统。
5.1.2 安装流程
1.访问 Ollama 官网 Windows 下载页:Download Ollama on Windows,获取安装包 OllamaSetup.exe

2.运行安装程序,点击 Install 执行一键安装。
Windows 版本安装包默认不支持自定义程序本体安装目录,程序本体默认安装至:C:\Users\<用户名>\AppData\Roaming
模型文件默认存储路径:C:\Users\<用户名>\.ollama\models,后续可以在图形化设置里修改存储位置。
3.安装完成后 Ollama 服务会自动启动,可以打开任务管理器,查看 ollama.exe 进程确认运行状态。
或者在浏览器中输入:http://localhost:11434,看到 ollama is running 时说明 ollama 服务已经启动了。
5.2 交互方式
Windows 环境提供了两类交互入口:图形化界面、命令行终端,满足不同开发、调试场景。
5.2.1 图形化界面
- 安装完成自带原生图形客户端,开箱即用
- 支持新建对话会话、切换模型、调整模型参数等可视化操作
- 不用记忆命令,适合日常快速调试、对话测试

5.2.2 命令行终端
- 命令操作逻辑和 Ubuntu 平台完全一致,ollama 所有核心命令跨平台通用
- 版本校验命令,在 CMD / PowerShell 中执行:
ollama -v
示例输出:ollama version is 0.12.3
5.3 图形化设置详解
打开 Ollama 客户端,点击 Settings 进入设置页面,下面是各个配置项的说明:
5.3.1 Expose Ollama to the network(网络暴露)
- 功能:开启该选项之后,允许局域网内其他设备、服务访问本机 Ollama 推理接口
- 适用场景:把 Windows 本地部署的模型,作为局域网共享推理服务,给其他机器(Ubuntu、其他 PC)调用,也就是我们前面 C++ SDK 对接本地 Ollama 的场景
5.3.2 Model location(模型存储位置)
- 功能:修改模型文件在本地的存放目录
- 优化建议:建议修改到非系统盘(D 盘等),大模型体积很大,避免大量模型文件占用 C 盘空间,导致系统盘容量不足
5.3.3 Context length(上下文长度)
- 功能:控制模型能够记忆、带入对话的历史消息最大长度
- 可选档位:4k、8k、16k、32k、64k、128k
- 配置原则:不是越大越好,上下文越长,显存、内存消耗越高,需要结合硬件显存大小和业务场景权衡选择
5.3.4 Airplane mode(飞行模式)
- 关闭状态:可以正常连接 Ollama 官方模型库,在线拉取、下载新模型
- 开启状态:强制所有数据本地运行,断开和云端服务的连接,只能加载已经提前下载到本机的模型,无法在线拉取模型
5.3.5 Reset to defaults
- 功能:一键把上面所有配置项恢复成出厂默认值

六、Ollama 通用核心配置与机制
6.1 环境变量配置
环境变量为全平台通用配置方式,用来修改 Ollama 的默认行为,它的优先级高于图形化配置。
6.1.1 模型存储配置
- OLLAMA_MODELS:指定模型文件存放目录
- 默认路径:Windows 下为
C:\Users\<用户名>\.ollama\models,Linux 下为~/.ollama/models - 优化建议:迁移到非系统盘,避免占用系统盘存储空间,例如 Windows 可设置为
D:\ApplyTool\ProgramTool\ollama\models
- 默认路径:Windows 下为
6.1.2 服务网络配置
- OLLAMA_HOST:Ollama 服务监听的网络 IP 地址
- 默认值:
127.0.0.1,仅本机可以访问 - 局域网共享场景,需要开放给其他设备访问时,建议设置为
0.0.0.0
- 默认值:
- OLLAMA_PORT:Ollama 服务监听端口
- 默认端口:
11434 - 如果端口被其他程序占用产生冲突,可以修改为其他空闲端口,如 8080
- 默认端口:
- OLLAMA_ORIGINS:允许发起 HTTP 请求的来源地址
- 多个来源使用半角逗号分隔;本地无跨域限制需求时,可以直接填写星号
*,放行所有来源
- 多个来源使用半角逗号分隔;本地无跨域限制需求时,可以直接填写星号
6.1.3 性能与并发配置
- OLLAMA_KEEP_ALIVE:模型加载进内存之后的存活时长
- 默认值:
5m,也就是 5 分钟 - 取值规则:纯数字代表单位为秒;填 0 代表请求处理完成后立刻卸载模型;负数代表永久驻留内存
- 优化建议:可以设置为
24h,减少模型反复加载卸载的开销,加快多次对话的响应速度
- 默认值:
- OLLAMA_NUM_PARALLEL:并发请求处理数量
- 默认值:
1,同一时刻串行处理请求 - 可以根据本机显卡算力、内存大小适度调高,提升并发接待能力
- 默认值:
- OLLAMA_MAX_QUEUE:请求队列最大长度
- 默认值:
512 - 当排队请求超过该阈值,新到来的请求会直接丢弃;需要根据业务流量调整阈值
- 默认值:
- OLLAMA_MAX_LOADED_MODELS:内存中同时驻留的最大模型数量
- 默认值:
1,同一时间只允许一个模型加载在内存中
- 默认值:
- OLLAMA_DEBUG:调试日志开关
- 研发调试阶段设置为
1,会输出完整详细的日志信息,方便定位异常、排查问题
- 研发调试阶段设置为
结束语
本章我们完整梳理了本地大模型的落地路线,对比了云端接入与私有化部署各自的适用场景,同时系统学习了 Ollama 在 Ubuntu、Windows 环境下的安装、运维、核心命令、存储结构以及环境变量配置。
Ollama 对外提供了兼容 OpenAI 规范的 HTTP 接口,这也意味着我们之前搭建的 SDK 抽象架构可以继续复用,只需要新增对应的 Ollama Provider,适配它的接口细节,就能实现本地模型和云端模型统一调用。
下篇文章我们就基于本章掌握的 Ollama 接口规范,开始编写 OllamaProvider 的代码,完成本地大模型在 SDK 里的接入,实现一套框架同时支持云端、本地两类大模型。
更多推荐
所有评论(0)