小白玩转大模型开发（3）：大模型本地部署与调用图1

> 作者：李剑锋

1. 前言

1.1 课程回顾

在中，我们已经完成了大模型应用开发的基础准备工作。首先，我们学习了如何使用 VSCode 作为代码编辑器，了解了项目文件夹、代码文件、终端和命令面板等基本操作；随后，我们配置了 Miniconda 和 Python 环境，学习了虚拟环境创建、第三方库安装等内容，并掌握了 .py 文件和 .ipynb 文件的基本运行方式。通过这些准备工作，我们已经具备了使用 Python 编写和运行大模型应用程序的基础能力。

在此基础上，我们进一步学习了大模型 API 调用的基本流程。通过 API_KEY、base_url、model、messages 和 response 等核心概念，我们理解了本地 Python 程序是如何向大模型平台发送请求，并接收模型返回结果的。随后，我们使用 openai 库完成了一次基础的大模型调用，打通了“本地代码 → 云端平台 → 大模型回复”的完整链路。

不过，上节课介绍的调用方式，本质上属于云端模型调用。也就是说，大模型并没有真正运行在我们的本地电脑上，而是运行在厂商提供的云端服务器中。本地电脑主要负责通过代码发送请求、接收结果和处理回复内容。这样的方式上手简单、硬件要求低，只要本地能够运行 Python 程序并连接网络，就可以调用能力较强的云端大模型，因此非常适合作为大模型应用开发的入门方式。

但是在实际开发中，除了调用云端模型之外，还有另一种非常重要的方式：将大模型部署到本地，然后在本地进行调用。本地部署后，模型不再依赖云端平台完成推理，而是直接运行在自己的电脑或服务器上。这样一来，我们可以更直观地理解模型从“文件”变成“服务”的过程，也能进一步掌握大模型应用开发中更底层、更工程化的调用方式。

当然，本地部署也并不是完全没有门槛。相比云端 API 调用，本地部署对电脑硬件会有更高要求，尤其是对 GPU 显存、内存和存储空间都有一定要求。一般来说，参数规模较小的模型更适合普通电脑或入门实验使用，例如 1B 以内的小模型（十亿参数），经过量化后通常需要几 GB 左右的显存或内存即可运行；而参数规模更大的模型，例如 7B、14B 甚至更大的模型，就可能需要十几 GB 到几十 GB 显存，甚至需要专门的服务器或多卡环境。因此，本节课不会一开始就追求部署大参数模型，而是先以本地小模型为主，帮助大家理解本地部署和调用的基本流程。

此外，本节课选择的是简单易上手的本地部署工具 —— Ollama。通过 Ollama，我们可以较方便地下载、运行和调用本地小模型，并且还能继续使用类似 OpenAI 的接口风格进行程序调用。这样既能降低本地部署的学习门槛，也能帮助大家把上节课学到的 API 调用知识迁移到本地模型场景中。

1.2 开源大模型简介

在正式学习大模型本地部署之前，我们需要先弄清楚一个基础问题：模型本地部署时，我们到底部署的是什么？

从表面上看，我们好像是在“部署一个大模型”；但从实际文件角度来看，本地部署的核心通常是一组已经训练好的模型权重文件。所谓模型权重，可以简单理解为大模型经过大量数据训练之后得到的一组参数。这些参数记录了模型在训练过程中学习到的语言规律、知识关联和生成能力，是模型具备理解、生成和推理能力的关键基础。

也就是说，我们在本地部署模型时，并不是从零开始训练一个大模型，而是把大模型厂商或研究机构已经训练好的模型成果下载到本地，再通过 Ollama、vLLM、LMDeploy、Transformers 等推理框架将模型加载起来，使它能够根据用户输入进行推理并生成回答。除了模型权重之外（下图的 .safetensors 文件），一个模型通常还需要配合配置文件、分词器文件等内容。配置文件用于描述模型结构、上下文长度等信息，分词器则负责把自然语言文本转换成模型能够处理的 token。只有这些文件和推理框架配合起来，模型才能真正“跑起来”。

早期比较有代表性的开放模型是 Meta 推出的 LLaMA 系列。它推动了开源大模型生态的发展，让研究者和开发者能够在本地环境中研究和使用大语言模型。

随后，越来越多模型团队和大模型厂商也开始开放自己的模型。例如 Qwen、DeepSeek、GLM、Kimi 等系列模型中，都有一些可以下载、部署或二次开发的开放版本。这些模型的出现，使得个人开发者、高校实验室和中小企业不再只能依赖云端 API，也可以在自己的电脑或服务器上运行大模型，并根据实际需求进行本地应用开发、私有化部署或进一步微调。

那么，既然训练大模型需要投入大量算力、数据和工程成本，为什么很多厂商还愿意开放模型呢？这背后其实有多方面原因。

首先，开放模型可以扩大模型本身的影响力。当一个模型被更多开发者下载、测试和使用后，它的知名度、讨论度和社区活跃度都会不断提升。其次，开源社区能够帮助厂商发现模型在不同应用场景中的问题。例如，在中文问答、代码生成、数学推理、工具调用、行业知识应用等任务中，开发者可能会遇到不同类型的效果问题，这些真实反馈可以反过来帮助模型团队优化后续版本。再次，开放模型也有助于吸引更多开发者围绕模型构建工具、插件、教程、应用案例和微调方案，从而形成更完整的模型生态。

不过需要注意的是，我们平时说的“开源大模型”，并不一定意味着厂商把所有内容都完整开放出来。很多时候，厂商开放的主要是模型权重和配套文件，例如配置文件、分词器文件、模型说明和许可证等；而原始训练数据、完整训练脚本、数据清洗流程和全部训练细节，通常并不会完全公开。因此，更准确地说，很多所谓“开源大模型”其实更接近于开放权重模型。开发者可以基于这些已经训练好的权重进行本地部署、推理调用和一定程度的二次开发，但并不等于获得了模型从零训练的完整生产过程。

1.3 本地部署简介

前面我们已经了解了什么是开源大模型。简单来说，开源大模型通常是大模型厂商或研究机构开放出来的一组模型权重和配套文件。我们不需要从零训练模型，而是可以直接下载这些已经训练好的模型成果，并在自己的电脑或服务器上运行。

那么接下来就会出现一个新的问题：下载到本地的模型权重，怎样才能真正被我们使用？

模型权重本身只是一组保存在磁盘中的参数文件。它记录了模型训练之后得到的核心能力，但它并不能像普通软件一样直接双击运行，也不能自动接收用户输入并返回回答。如果只是把模型文件下载到了电脑里，模型其实还只是“躺在文件夹中的文件”，并没有真正变成一个可以被程序调用的系统。因此这时候，就需要进行模型部署。

所谓模型部署，就是把已经训练好的模型权重和相关配置文件加载起来，并通过一定的运行框架，让模型能够接收输入、完成推理、返回结果。换句话说，部署的核心目标不是让模型“重新学习知识”，而是让模型真正“用起来”。如果从大模型应用开发的角度来看，部署可以理解为：把模型从一个本地文件，变成一个可以被外部程序访问的模型服务。

例如，当我们使用 Ollama、vLLM、LMDeploy 或 Transformers 等工具部署模型时，这些工具会负责加载模型权重、初始化推理环境、管理模型运行过程，并对外提供调用方式。用户或程序只需要把问题发送给这个模型服务，模型服务就会调用本地模型进行推理，然后把生成结果返回给调用方。

在实际开发中，部署后的模型通常会以 API 接口 的形式对外提供能力。也就是说，我们可以在本地启动一个模型服务，让它监听某个地址和端口。例如，模型服务可能运行在：

http://localhost:11434

其中，localhost 表示本机，11434 表示服务端口。只要这个服务正常运行，本地 Python 程序就可以通过接口把问题发送给它，并接收模型返回的回答。

这和上一节课学习的云端 API 调用其实非常相似。区别在于，云端 API 调用时，base_url 指向的是大模型厂商提供的云端服务器；而本地部署时，base_url 指向的是我们自己电脑或服务器上运行的模型服务。

从代码调用的角度看，只要本地模型服务提供了 OpenAI 兼容接口，我们仍然可以继续使用前面学过的 openai 库进行连接。变化的主要是 base_url 和 model。例如，之前调用云端模型时，base_url 可能是某个平台的 API 地址；而调用本地 Ollama 模型时，base_url 就可以改成本地服务地址。

如果模型部署在自己的电脑上，那么程序可以直接通过本地地址访问；如果模型部署在远程服务器上，也可以通过开放服务端口的方式，让本地电脑连接服务器上的模型服务。这样一来，本地程序虽然运行在自己的电脑上，但实际推理可以由远程服务器上的模型完成。

因此，模型部署可以简单概括为一句话：

模型部署，就是把已经训练好的模型运行起来，并封装成一个可以被程序调用的服务。

1.4 Ollama 简介

在众多模型部署工具中，Ollama 更适合作为本地大模型运行与轻量级服务化调用的入口工具。它的核心价值并不在于追求极致的推理吞吐或复杂的生产级集群能力，而在于将开源大模型的下载、管理、运行和 API 调用流程进行了统一封装，使本地大模型的使用门槛显著降低。

从使用方式来看，Ollama 提供了一套非常简洁的命令行接口。用户可以通过 ollama pull 下载模型，通过 ollama run 直接运行模型并进入交互式对话，通过 ollama list 查看本地已有模型，通过 ollama ps 查看当前正在运行或保留在内存中的模型状态，也可以通过 ollama stop 停止指定模型并释放相关资源。相比手动编写 Transformers 推理代码，这种方式隐藏了大量底层细节，更适合快速完成本地模型体验和原型验证。

更重要的是，Ollama 不只是一个命令行对话工具。它在本地运行后，会默认启动模型服务，并提供本地 API 调用能力。也就是说，模型不仅可以在终端中进行交互，也可以被 Python 程序、Web 应用、RAG 系统、Agent 系统或其他业务程序调用。对于大模型应用开发来说，这一点非常关键，因为它意味着本地模型可以从“手动运行的程序”进一步变成“可被外部系统访问的模型服务”。

Ollama 还支持 OpenAI 兼容接口。通常情况下，本地 Ollama 服务地址为：

http://localhost:11434

其中，Ollama 原生 API 一般使用 /api 路径，而 OpenAI 兼容接口通常使用：

http://localhost:11434/v1/

这意味着在 Python 中可以直接使用 OpenAI SDK 调用本地模型，只需要将 base_url 指向 Ollama 的本地服务地址，并将 model 设置为本地已经下载的模型名称即可。这样一来，原本面向在线模型服务编写的调用代码，也可以较为平滑地迁移到本地模型服务上。

总体来看，Ollama 的定位可以概括为：面向本地大模型运行的轻量级模型管理与服务化工具。它既可以帮助用户快速体验开源模型，也可以通过本地 API 和 OpenAI 兼容接口，将模型接入到更完整的应用开发流程中。

因此，在学习大模型部署时，Ollama 非常适合作为第一个实践工具。它可以帮助我们先建立对本地模型运行、模型服务、API 调用和应用集成的基本认识。等这些基础概念清楚之后，再进一步学习 LMDeploy、vLLM、SGLang 等高性能部署框架时，就能够更容易理解它们为什么需要关注推理后端、显存管理、量化优化、并发调度和服务稳定性等更深层次的问题。

那事不宜迟，接下来我们就来看看如何来在本地实现 Ollama 本地模型部署吧！

2. Ollama 环境准备

在正式使用 Ollama 运行本地大模型之前，需要先完成软件安装、命令行验证以及基础配置。对于 Windows 用户而言，Ollama 的安装流程相对简单，但在实际使用过程中，仍然可能遇到命令无法识别、后台服务未启动、模型存储路径不合理等问题。因此，本节将从安装、常见报错处理和基础配置三个方面进行说明。

2.1 Ollama 安装

进入官网（https://ollama.com/）并点击右上角的 Download：

在下载页面中选择 Download for Windows：

随后下载 Windows 安装程序 OllamaSetup.exe：

下载完成后，双击安装程序，点击 Install 即可开始安装：

安装完成后，可以看到 Ollama 的启动界面：

为了确认 Ollama 是否安装成功，可以重新打开 PowerShell 或命令行窗口，执行以下命令：

果能够正常输出版本号，就说明 Ollama 已经安装完成，并且命令行可以正确识别 ollama 指令。

2.2 常见报错处理

2.2.1 无法识别 `ollama` 指令

在安装完成后，如果重新打开终端并执行 ollama list、ollama --version 等命令时出现以下报错：

ollama : 无法将“ollama”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径
正确，然后再试一次。
所在位置 行:1 字符: 1
+ ollama list
+ ~~~~~~
    + CategoryInfo          : ObjectNotFound: (ollama:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

通常说明 Windows PowerShell 当前无法找到 ollama.exe 可执行文件。这个问题并不代表 Ollama 安装失败，也不代表模型服务异常，而是当前系统的 PATH 环境变量中没有包含 Ollama 的安装路径。

可以先在 PowerShell 中执行以下命令，检查 Ollama 可执行文件是否存在：

Test-Path "$env:LOCALAPPDATA\Programs\Ollama\ollama.exe"

如果返回结果为 True，说明 Ollama 已经安装在本地，只是环境变量尚未配置正确。

接下来可以打开 Windows 的环境变量设置，找到用户变量或系统变量中的 Path：

双击进入 Path 后，新建一项内容：

%LOCALAPPDATA%\Programs\Ollama

然后保存设置后，关闭当前终端并重新打开 PowerShell，再次执行：

如果能够正常执行，就说明环境变量已经配置成功。

2.2.2 后台服务没有正常启动

如果在运行 Ollama 时出现以下提示：

Error: timed out waiting for server to start

Warning: could not connect to a running Ollama instance

通常说明 Ollama 客户端没有连接到正在运行的本地 Ollama Server。也就是说，ollama.exe 命令本身可以被识别，但后台服务没有正常启动，或者当前服务状态异常。

这类问题可以优先尝试以下处理方式：

关闭当前正在运行的 Ollama；
重新启动 Ollama 应用；
重新打开终端，再次执行相关命令。

重启后，可以通过命令行重新检查模型列表或服务状态：

在 Windows 环境中，Ollama 通常会随系统启动自动运行。如果开机时网络状态不稳定，或者后台服务初始化异常，就可能出现客户端无法连接 Server 的情况。一般情况下，重新启动 Ollama 后即可恢复正常。

2.3 基础配置

在正式下载和运行模型之前，建议先进入 Ollama 的 Settings 页面，对几个关键配置项进行确认。对于本地模型运行来说，比较重要的配置主要包括账号与云端能力、自动更新、网络访问权限、模型存储位置以及上下文长度设置。

这些配置会直接影响 Ollama 的使用方式、模型保存位置、资源占用和网络访问范围。

2.3.1 账号与云端能力

首先是 Ollama account 和 Cloud 相关设置。

Ollama account 表示当前是否登录 Ollama 账号。如果只是运行本地模型，例如使用 ollama run 启动模型，或者通过本地 API 调用模型，一般不需要登录账号。未登录状态下，仍然可以完成大部分本地模型运行、模型管理和本地 API 调用任务。

Cloud 用于启用 Ollama 的云端模型和 Web Search 等在线能力。也就是说，Ollama 除了可以运行本地模型，也可以在启用云端能力后使用部分在线模型或在线功能。

不过，如果当前目标是学习本地大模型运行、管理和调用，那么云端能力并不是必要配置。是否登录账号、是否启用云端能力，可以根据实际使用需求自行决定。

登录账号后，可以使用部分云端模型进行对话。不过需要注意，不同账号类型能够使用的模型范围可能不同，免费版本通常只开放部分模型能力。

2.3.2 更新与网络访问

第二部分是 Auto-download updates 和 Expose Ollama to the network。

Auto-download updates 表示是否自动下载 Ollama 更新。开启后，Ollama 可以自动获取较新的版本，从而获得新的功能、模型支持和问题修复。对于普通使用场景，开启自动更新可以减少手动维护成本；但如果需要保持实验环境或文章示例的一致性，也可以选择关闭自动更新，避免不同版本之间的行为差异。

Expose Ollama to the network 是一个需要重点关注的网络访问选项。默认情况下，Ollama 主要面向本机访问，通常通过以下地址调用本地模型服务：

http://localhost:11434

如果开启 Expose Ollama to the network，局域网内的其他设备或服务就可能访问当前电脑上的 Ollama 服务。这在某些场景中比较有用，例如：

在一台性能较好的主机上运行 Ollama，其他设备通过局域网调用；
多个本地应用需要访问同一个模型服务；
在小型内部环境中进行模型服务共享。

但需要注意，开启网络访问也意味着 Ollama 服务不再只对本机开放。如果当前设备处在公共网络或不可信网络环境中，不建议随意开启该选项，以免带来不必要的安全风险。

2.3.3 本地模型存储

第三部分是 Model location，也就是模型文件的本地保存位置。

在 Ollama 中，通过 ollama pull 或 ollama run 下载的模型都会保存到本地模型目录中。例如图中显示的路径为：

C:\Users\76391\.ollama\models

这表示当前 Ollama 下载的模型会默认存放在该用户目录下的 .ollama\models 文件夹中。对于 Windows 用户来说，这个目录通常位于 C 盘用户目录下。

在实际使用中，不建议长期将大模型文件保存在 C 盘。原因很简单：大模型文件通常体积较大，即使是较小规模的模型，也可能占用数 GB 磁盘空间；如果后续下载 7B、14B 或更大规模的模型，磁盘占用会进一步增加。模型数量越多，C 盘空间压力就越明显，甚至可能影响系统运行和软件安装。

因此，更推荐提前在空间充足的磁盘中新建专门的模型缓存目录，例如：

D:\OllamaCache

然后在 Model location 中点击 Browse，将模型保存位置修改到该目录。这样后续通过 Ollama 下载的模型就会保存到新的路径中，避免继续占用 C 盘空间。

2.3.4 上下文长度设置

最后一部分是 Context length，也就是上下文长度设置。

上下文长度可以理解为模型在一次对话或生成过程中最多能够参考多少 token。上下文越长，模型能够看到的历史对话、输入文本或文档内容就越多；上下文越短，模型能够利用的信息范围就越有限。

在设置页面中，Ollama 提供了多个上下文长度选项，包括：

其中，4k、8k、32k 等表示大致的 token 数量。较大的上下文长度更适合长文本处理、长文档问答、多轮对话和代码文件分析等任务。

但是，上下文长度并不是越大越好。更大的上下文长度通常意味着更高的内存或显存占用，同时也可能降低推理速度。如果本地设备配置有限，盲目设置过大的上下文长度，可能导致模型响应变慢，甚至出现内存不足、显存不足或模型无法正常运行等问题。

因此，在本地实验或普通应用场景中，可以优先使用默认值，或者选择较保守的上下文长度，例如 4k 或 8k。当确实需要处理长文本、长对话或大文档时，再根据硬件资源逐步调高上下文长度，会更加稳妥。

3. Ollama 本地部署

完成 Ollama 的安装与基础配置后，就可以开始进行模型查阅、模型下载、本地运行、API 调用以及资源释放等操作。Ollama 的核心优势在于，它将本地模型管理和模型服务调用进行了统一封装，使用户可以通过较少的命令完成从模型获取到本地推理的完整流程。

3.1 模型查阅

在使用 Ollama 之前，首先需要确定要运行的模型。Ollama 官方提供了模型检索页面，可以查看当前支持下载和运行的模型：

https://ollama.com/search

例如，可以在模型库中搜索 Qwen 系列模型：

Ollama 模型库通常会为模型标注不同能力标签，例如：

vision：表示模型具备视觉理解能力；
thinking：表示模型支持思考或推理模式；
tools：表示模型支持工具调用能力；
embedding：表示模型可用于文本向量化任务。

这些标签可以帮助用户根据实际需求选择合适的模型。例如，如果目标是构建图文理解应用，可以优先选择带有 vision 标签的模型；如果目标是构建 RAG 系统，则可以关注 embedding 类型模型；如果需要进行 Agent 工具调用实验，则可以选择支持 tools 的模型。

在本文示例中，为了兼顾本地运行门槛和模型能力展示，选择体量较小的 qwen3.5:0.8b 模型作为演示对象。该模型规模较小，更适合在本地设备上快速下载和运行。

3.2 模型下载与运行

确定模型名称后，可以通过命令行或 Python 程序调用 Ollama 模型。Ollama 的模型名称需要与官方模型库或本地模型列表中的名称保持一致，例如：

qwen3.5:0.8b

在 Ollama 中使用模型时，通常可以分为两个步骤：先下载模型，再运行模型。这样可以让我们更清楚地理解模型文件是如何被拉取到本地，以及后续如何通过命令行启动模型进行对话。

3.2.1 使用 `ollama pull` 下载模型

如果我们只是希望先把模型下载到本地，而不立即进入对话模式，可以使用 ollama pull 命令。例如：

ollama pull qwen3.5:0.8b

该命令的作用是从 Ollama 模型库中拉取指定模型，并将模型文件保存到前面配置的模型存储目录中。下载过程中，终端会显示模型文件的拉取进度。

如果模型此前已经下载完成，再次执行 ollama pull 时，Ollama 通常会检查本地文件状态，并避免重复下载相同内容。也就是说，ollama pull 更适合用于提前准备模型文件，例如在正式上课、实验演示或部署前，先将模型下载到本地。

3.2.2 使用 `ollama run` 运行模型

模型下载完成后，就可以使用 ollama run 命令运行模型。例如：

ollama run qwen3.5:0.8b

执行该命令后，Ollama 会启动对应模型，并在终端中进入交互式对话模式。此时，我们可以直接输入问题，模型会在命令行中返回回答。

需要注意的是，ollama run 不仅可以运行本地已经存在的模型，也可以在模型尚未下载时自动拉取模型文件。也就是说，如果本地还没有 qwen3.5:0.8b，直接执行：

ollama run qwen3.5:0.8b

Ollama 会先自动下载该模型，下载完成后再进入交互式对话模式。

因此，ollama pull 和 ollama run 的区别可以简单理解为：

ollama pull：只下载模型，不进入对话；
ollama run：运行模型，如果本地没有模型，会先下载再运行。

如果需要退出当前对话模式，可以使用快捷键：

Ctrl + D

通过这种方式，我们就可以完成从模型下载到模型运行的完整流程。对于初学者来说，建议先使用 ollama pull 理解模型下载过程，再使用 ollama run 启动模型进行交互式测试。

3.3 模型列表与运行状态查看

在下载和运行多个模型之后，可以通过命令行查看本地已经存在的模型列表。

ollama list

执行后，Ollama 会列出当前本地已经下载的模型，包括模型名称、模型 ID、模型大小以及更新时间等信息。

如果需要查看当前正在运行或仍然保留在内存、显存中的模型，可以使用：

ollama ps

例如，先启动模型：

ollama run qwen3.5:0.8b

然后重新打开一个终端窗口，执行：

ollama ps

此时可以看到当前模型的运行状态：

从示例结果可以看到，qwen3.5:0.8b 当前仍然保留在 GPU 上，占用约 2.3GB 资源，并使用 4096 的上下文长度。具体字段含义如下：

字段	含义
`NAME`	当前运行或保留中的模型名称
`SIZE`	模型运行时占用的大致资源大小
`PROCESSOR`	当前模型主要运行在哪类处理器上，例如 CPU 或 GPU
`CONTEXT`	当前模型使用的上下文长度
`UNTIL`	模型预计继续保留的时间

ollama ps 对于观察本地资源占用非常有用。尤其是在显存有限的环境中，可以通过该命令判断模型是否仍然占用 GPU 资源，从而决定是否需要手动停止模型。

3.4 本地模型服务调用

到这里，模型已经能够在本地正常运行了。但如果只是停留在命令行对话模式，它更像是一个“本地聊天工具”，还没有真正接入到我们的 Python 程序或应用系统中。对于大模型应用开发来说，我们更关心的是：能不能像调用云端大模型 API 一样，通过代码调用这个本地模型？

答案是可以的。Ollama 在本地运行后，会提供一个本地模型服务。Python 程序可以通过接口把用户问题发送给这个服务，再由 Ollama 调用本地模型完成推理，并将结果返回给程序。这样一来，本地模型就不只是能在终端中聊天，而是可以进一步接入到 Web 应用、RAG 系统、Agent 系统或其他业务程序中。

Ollama 默认的本地服务地址为：

http://localhost:11434

其中，localhost 表示当前电脑本机，11434 是 Ollama 默认使用的服务端口。只要 Ollama 服务正常运行，我们就可以把它看作一个运行在本地的大模型服务。

更重要的是，Ollama 支持使用 OpenAI 格式 进行调用。也就是说，我们前面学习过的 openai Python 库仍然可以继续使用。区别只是：之前调用云端模型时，base_url 指向的是云端大模型平台；现在调用本地模型时，base_url 指向的是本地 Ollama 服务地址。

因此，从代码结构上看，本地模型调用和云端模型调用非常相似。主要变化集中在两个地方：一是 base_url 改成本地服务地址，二是 model 改成本地已经下载好的模型名称。

在使用 openai 库调用 Ollama 时，通常会将 base_url 写成：

http://localhost:11434/v1/

3.4.1 语言模型调用

首先来看最基础的语言模型调用。语言模型调用主要处理文本输入和文本输出，适合完成问答、解释、摘要、翻译、代码生成等任务。

示例代码如下：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="qwen3.5:0.8b",
    messages=[
        {
            "role": "system",
            "content": "你是一个人工智能课程助教，回答应准确、简洁。"
        },
        {
            "role": "user",
            "content": "请用三句话解释什么是大语言模型。"
        }
    ],
    temperature=0,
    max_tokens=512,
    reasoning_effort="none"
)

print(response.choices[0].message.content)

这段代码的整体结构和云端大模型 API 调用非常接近。不同之处在于，这里的 base_url 指向的是本地 Ollama 服务，而不是云端模型平台。

这里的几个参数需要重点理解：

base_url：指向本地 Ollama 模型服务地址。这里填写 http://localhost:11434/v1/，表示 Python 程序会按照 OpenAI 格式访问本机上的 Ollama 服务；
api_key：是 openai 库所需参数。本地调用 Ollama 时通常不会真正校验密钥，因此可以填写 ollama 作为占位值；
model：用于指定要调用的本地模型名称，应与 ollama list 中显示的模型名称保持一致；
messages：用于传入对话消息，其中 system 表示系统设定，user 表示用户输入；
temperature：用于控制生成结果的随机性，设置为 0 时，模型输出通常更加稳定；
max_tokens：用于限制本次回答最多生成的 token 数，避免模型输出过长；
reasoning_effort：用于控制是否启用模型的思考模式。这里设置为 "none"，表示尽量关闭思考过程，只返回最终回答。

需要注意的是，不同模型或不同 Ollama 版本对参数的支持情况可能略有差异。如果运行时报错提示某个参数不支持，可以先删除该参数，再重新运行代码。例如，如果 reasoning_effort="none" 报错，可以先将这一行去掉。

运行后，可以看到模型返回类似结果：

大语言模型是一种基于深度学习的人工智能模型，能够理解和生成自然语言文本。

它通过大规模文本数据训练，学习语言结构、知识关联和表达方式，从而具备问答、写作、翻译和代码生成等能力。

简单来说，大语言模型就是一种可以根据用户输入生成合理文本回复的智能系统。

到这里，我们就完成了 Ollama 的本地模型服务化调用。与直接在终端中使用 ollama run 对话不同，使用 openai 库调用本地模型，可以让模型更方便地接入 Python 程序、Web 应用、RAG 系统、Agent 系统或其他业务程序。

3.4.2 图片输入调用

除了普通文本对话之外，如果本地模型本身支持视觉理解能力，那么也可以通过 OpenAI 格式向模型传入图片，让模型根据图片内容进行描述、识别和问答。

需要注意的是，图片输入能力并不是所有模型都具备，只有视觉语言模型才支持这类任务。因此，在运行图片输入示例之前，需要先确认当前模型是否支持 vision 能力。如果当前模型不支持图片输入，就需要更换为支持视觉理解的模型。

在调用方式上，图片输入与文本输入的主要区别在于：messages 中的 content 不再只是一个字符串，而是一个列表。这个列表中既可以放入文本问题，也可以放入图片内容。

不过需要特别说明的是，在 Ollama 的 OpenAI 格式调用中，图片通常不能直接使用网络图片地址，而是需要先将图片转换为 base64 编码，再以 data:image/...;base64,... 的形式传入模型。因此，如果图片来自网络地址，通常需要先下载图片，再完成编码转换。

下面以一张老虎图片为例进行测试：

import base64
import requests
from openai import OpenAI

image_url = "https://raw.githubusercontent.com/open-mmlab/mmdeploy/main/tests/data/tiger.jpeg"

# 1. 下载图片
image_response = requests.get(image_url, timeout=30)
image_response.raise_for_status()

# 2. 将图片内容转为 base64 编码
image_base64 = base64.b64encode(image_response.content).decode("utf-8")

# 3. 调用本地视觉模型
client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="qwen3.5:0.8b",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请描述这张图片中的主要内容。"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_base64}"
                    }
                }
            ]
        }
    ],
    temperature=0,
    max_tokens=512
)

print(response.choices[0].message.content)

在这段代码中，content 列表包含了两部分内容：

第一部分是文本输入，用于告诉模型“我们希望它完成什么任务”；
第二部分是图片输入，用于把图片传递给模型进行理解。

其中，下面这部分代码：

{
    "type": "image_url",
    "image_url": {
        "url": f"data:image/jpeg;base64,{image_base64}"
    }
}

表示向模型传入一张经过 base64 编码后的图片。模型接收到文本问题和图片后，会结合图片内容生成回答。此时模型可能的回复如下所示：

这张图片主要展示了一只正在休息的**老虎**。

以下是图片中的主要内容描述：

1.  **主体**：画面中心是一只体型庞大的老虎，它正趴伏在绿色的草地上。它的身体舒展，前爪向前伸展，姿态显得非常放松和警觉。
2.  **细节**：老虎的皮毛呈现出标志性的橙黄色底色，上面布满了黑色的条纹。它的耳朵竖立，目光直视前方，似乎在观察周围的环境。
3.  **环境**：背景是一片郁郁葱葱的草地，阳光透过树叶洒下斑驳的光影，营造出一种宁静

如果运行时报错，通常有以下几种可能原因：

当前模型不支持视觉输入，需要更换为支持 vision 能力的模型；
Ollama 版本较旧，对多模态输入支持不完整，可以尝试更新 Ollama；
图片没有正确转换为 base64 编码，或者编码格式书写不正确；
模型名称填写错误，需要使用 ollama list 查看本地实际存在的模型名称；
网络无法正常访问原始图片地址，导致图片下载失败。

简单来说，图片输入调用的核心思路就是：先准备文本问题，再准备图片内容，最后按照 OpenAI 多模态消息格式一起发送给本地视觉模型。

3.4.3 视频输入调用

除了图片理解之外，一些视觉语言模型也可以用于视频内容理解。不过在本地部署环境中，视频输入通常比图片输入更加复杂。因为视频本质上是由连续画面组成的，如果直接把完整视频文件传给模型，可能会带来较高的显存占用、较长的处理时间，以及不同模型和框架之间的兼容性问题。

因此，在入门阶段，我们可以采用一种更稳妥的方式：先从视频中抽取若干关键帧，再把这些关键帧作为多张图片发送给模型分析。这样就可以把“视频理解”简化为“多张图片理解”，既容易理解，也更适合课堂演示。

下面以一个示例视频为例，先下载视频文件，再从中抽取若干帧，最后将这些帧转换为 base64 图片，并发送给本地视觉模型进行分析。

首先需要安装两个辅助库：

pip install opencv-python requests

然后可以使用下面的代码：

import base64
from pathlib import Path

import cv2
import requests
from openai import OpenAI

video_url = "https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4"
video_path = Path("baby.mp4")
frame_dir = Path("video_frames")
frame_dir.mkdir(exist_ok=True)

# 1. 下载视频
if not video_path.exists():
    response = requests.get(video_url, timeout=60)
    response.raise_for_status()
    video_path.write_bytes(response.content)

# 2. 从视频中抽取若干关键帧
cap = cv2.VideoCapture(str(video_path))

if not cap.isOpened():
    raise RuntimeError("视频文件打开失败，请检查视频路径或文件是否完整。")

total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))

if total_frames <= 0:
    cap.release()
    raise RuntimeError("无法读取视频帧数，请检查视频文件是否有效。")

# 这里抽取 4 帧，避免一次性输入过多图片导致推理变慢
sample_count = 4
frame_indices = [
    int(total_frames * (i + 1) / (sample_count + 1))
    for i in range(sample_count)
]

image_contents = []

for idx, frame_index in enumerate(frame_indices):
    cap.set(cv2.CAP_PROP_POS_FRAMES, frame_index)
    success, frame = cap.read()

    if not success:
        continue

    frame_path = frame_dir / f"frame_{idx + 1}.jpg"
    cv2.imwrite(str(frame_path), frame)

    image_base64 = base64.b64encode(frame_path.read_bytes()).decode("utf-8")

    image_contents.append(
        {
            "type": "image_url",
            "image_url": {
                "url": f"data:image/jpeg;base64,{image_base64}"
            }
        }
    )

cap.release()

if not image_contents:
    raise RuntimeError("没有成功抽取到视频帧，请检查视频文件。")

# 3. 调用本地视觉模型分析视频关键帧
client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="qwen3.5:0.8b",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "下面是从同一个视频中抽取的几个关键帧。请根据这些画面，简要概括视频中发生了什么。"
                },
                *image_contents
            ]
        }
    ],
    temperature=0,
    max_tokens=512
)

print(response.choices[0].message.content)

这段代码可以分成三个步骤理解。

第一步是下载视频。程序会从指定地址下载 baby.mp4，并保存到当前目录中。

第二步是抽取关键帧。视频本身由很多帧组成，如果全部传给模型，处理成本会比较高。因此这里仅抽取 4 张具有代表性的画面，用于近似表示视频内容。

第三步是调用本地模型。我们把抽取出来的关键帧转换成 base64 图片，并按照 OpenAI 格式放入 messages 中，让模型根据多张图片综合判断视频内容。

需要注意的是，这种方式并不是严格意义上的“逐帧视频理解”，而是通过抽取关键帧来完成视频内容概括。对于入门教学来说，这种方式更容易运行成功，也更能帮助学生理解：视频理解本质上可以看作对多个连续视觉画面的综合分析。

如果后续使用的是更专业的视觉语言模型部署框架，或者模型服务本身明确支持 video_url、视频帧采样和多模态处理参数，那么也可以进一步探索更完整的视频理解调用方式。但在本节课中，我们先采用关键帧抽取方案，重点理解本地模型服务如何从文本调用扩展到图片和视频内容理解。

最终可以看到模型返回的结果为：

一个戴眼镜的婴儿正在床上看书。

3.5 停止模型并释放资源

在使用 Ollama 运行模型后，即使我们已经退出了当前终端对话，模型也可能会在一段时间内继续保留在内存或显存中。这样做的好处是，当我们后续再次调用同一个模型时，可以减少重新加载模型所需的时间，提高响应速度。

但是，如果本地设备的显存或内存资源比较有限，模型持续占用资源也可能影响其他程序运行。因此，在确认暂时不再使用某个模型时，可以手动停止模型，从而释放相关资源。

首先，可以通过以下命令查看当前正在运行或仍然保留在内存、显存中的模型：

ollama ps

如果发现某个模型仍然处于运行或保留状态，并且暂时不再需要使用，就可以通过 ollama stop 命令将其停止。例如，停止 qwen3.5:0.8b 模型：

ollama stop qwen3.5:0.8b

停止完成后，可以再次执行：

ollama ps

如果列表中不再显示该模型，就说明模型已经停止运行，相关资源也已经释放。

需要注意的是，ollama stop 只是停止模型的运行状态，释放其占用的运行资源，并不会删除本地已经下载好的模型文件。也就是说，后续如果还需要使用该模型，仍然可以通过 ollama run qwen3.5:0.8b 再次启动。

3.6 移除本地模型

如果某个模型后续不再使用，或者希望释放本地磁盘空间，就可以将该模型从本地移除。需要注意的是，移除模型和停止模型并不是一回事。

ollama stop 主要用于停止正在运行或保留在内存、显存中的模型，释放的是运行资源；而 ollama rm 用于删除已经下载到本地的模型文件，释放的是磁盘空间。

如果需要移除某个本地模型，可以使用以下命令：

ollama rm 模型名称

例如要移除 qwen3.5:0.8b：

ollama rm qwen3.5:0.8b

执行完成后，Ollama 会删除该模型对应的本地文件。

删除完成后，可以再次执行：

ollama list

如果列表中不再显示 qwen3.5:0.8b，就说明该模型已经成功从本地移除。

后续如果还需要重新使用该模型，也可以再次通过 ollama pull 或 ollama run 将其下载到本地。例如：

ollama pull qwen3.5:0.8b

简单来说，ollama stop 适合在“暂时不用模型”时释放运行资源，而 ollama rm 适合在“以后不再使用模型”时删除模型文件、释放磁盘空间。

3.7 常用命令行

通过前面的学习，我们已经完成了 Ollama 模型查阅、下载、运行、查看、调用、停止和移除等操作。为了方便后续实验和复习，这里对本章常用的 Ollama 命令进行统一整理。

操作	命令	作用
查看版本	`ollama --version`	检查 Ollama 是否安装成功
下载模型	`ollama pull qwen3.5:0.8b`	将指定模型下载到本地，但不进入对话模式
运行模型	`ollama run qwen3.5:0.8b`	启动指定模型，并进入命令行交互式对话
查看本地模型	`ollama list`	查看当前已经下载到本地的模型列表
查看运行状态	`ollama ps`	查看当前正在运行或仍保留在内存、显存中的模型
停止模型	`ollama stop qwen3.5:0.8b`	停止指定模型，并释放相关运行资源
删除模型	`ollama rm qwen3.5:0.8b`	从本地移除指定模型文件，释放磁盘空间

其中，qwen3.5:0.8b 是本章示例中使用的模型名称。在实际使用时，需要根据自己下载的模型进行替换。例如，如果本地模型名称是 deepseek-r1:1.5b，那么运行模型时就应该写成：

ollama run deepseek-r1:1.5b

掌握这些常用命令后，就可以比较完整地完成 Ollama 本地模型的基本管理和调用操作。后续在开发 Gradio 页面、RAG 系统或 Agent 应用时，也可以基于这些命令快速准备和管理本地模型服务。

4. 总结

本章围绕 Ollama 本地部署与调用 展开，主要完成了从理论理解到实践操作的完整学习。

首先，我们回顾了上节课中云端大模型 API 调用的基本方式，并在此基础上引出了本地模型部署的意义。云端模型调用虽然使用简单、对本地硬件要求较低，但模型实际运行在厂商服务器上；而本地部署则是将模型运行在自己的电脑或服务器中，能够更直观地理解模型从“文件”变成“服务”的过程，也为后续私有化应用、离线应用和本地系统集成打下基础。

随后，我们介绍了开源大模型和本地部署的基本概念。本地部署的核心并不是从零训练一个大模型，而是下载大模型厂商或研究机构已经训练好的模型权重和配套文件，再通过推理框架将模型加载起来。模型权重可以理解为大模型训练完成后得到的一组参数，它记录了模型学习到的语言规律、知识关联和生成能力。只有将这些权重文件、配置文件、分词器文件与推理框架结合起来，模型才能真正运行并根据用户输入生成回答。

在理解了部署概念之后，本章进一步介绍了 Ollama。Ollama 是一个简单易上手的本地大模型运行与服务化工具，它将模型下载、模型管理、模型运行和接口调用进行了统一封装。相比直接使用复杂的高性能部署框架，Ollama 更适合作为本地模型部署的入门工具，能够帮助我们快速建立对“模型下载 → 模型运行 → 本地服务 → 程序调用”这一流程的整体认识。

在实践部分，我们完成了 Ollama 的安装、常见问题处理和基础配置。通过安装验证，我们确认了 ollama 命令是否能够正常使用；通过常见报错处理，我们了解了命令无法识别、后台服务未启动等问题的基本解决思路；通过基础配置，我们认识了模型存储位置、上下文长度、自动更新和网络访问等关键设置对本地模型运行的影响。

接着，我们围绕 Ollama 的核心命令进行了操作实践。通过模型库查阅模型，使用 ollama pull 下载模型，使用 ollama run 启动模型并进入命令行对话，使用 ollama list 查看本地模型列表，使用 ollama ps 查看模型运行状态，使用 ollama stop 停止模型并释放运行资源，最后使用 ollama rm 删除不再需要的本地模型文件。通过这些命令，我们已经能够完成本地模型的基本管理。

最后，我们学习了如何通过 openai 库调用本地 Ollama 模型服务。与直接在终端中使用 ollama run 对话不同，OpenAI 格式调用可以让本地模型接入 Python 程序、Web 应用、RAG 系统、Agent 系统或其他业务程序中。这样一来，本地模型就不只是一个可以在命令行中聊天的工具，而是进一步变成了可以被程序调用的模型服务。

通过本章学习，我们需要重点掌握三个核心认识：

第一，本地部署并不是重新训练模型，而是把已经训练好的模型权重运行起来。

第二，Ollama 可以帮助我们快速完成本地模型的下载、运行、查看、停止和移除等操作。

第三，通过 OpenAI 格式接口，本地 Ollama 模型也可以像云端模型一样被 Python 程序调用。

掌握这些内容后，我们就具备了本地小模型部署与调用的基本能力。后续在学习 Gradio 页面开发、RAG 知识库、Agent 智能体或更复杂的部署框架时，都可以基于本章内容继续拓展，将本地模型真正接入到完整的大模型应用开发流程中。

-- 完 --

课程过往内容：