大模型应用开发 / 系统课时
Windows 安装与环境验证
Windows 安装与环境验证
学习目标
完成本课后,你将能够:
- 在受支持的 Windows 系统中安装 Ollama
- 验证
ollama命令、后台应用和默认 API 是否正常- 检查默认端口
11434的监听状态- 根据日志、环境变量和驱动状态定位常见安装问题
安装前确认
Windows 版 Ollama 以原生应用运行。安装完成后,Ollama 会在当前用户会话中后台运行,并把 ollama 命令加入用户的 PATH。默认 API 地址为 http://localhost:11434。
正式安装前检查以下条件:
- 系统为 Windows 10 22H2 或更新版本。
- 当前用户目录所在磁盘至少有 4 GB 可用空间用于程序安装。
- 另有足够空间保存模型;模型文件可能占用数 GB 到数百 GB。
- NVIDIA 或 AMD GPU 驱动已安装并处于可用状态。
- 企业电脑没有拦截未知安装程序、后台启动项或本地端口。
- 终端使用 PowerShell 或 Windows Terminal,便于执行后续命令。
查看 Windows 版本:
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber预期输出:
WindowsProductName WindowsVersion OsBuildNumber
------------------ -------------- -------------
<WINDOWS_EDITION> <VERSION> <BUILD_NUMBER><WINDOWS_EDITION>、<VERSION> 和 <BUILD_NUMBER> 取决于当前系统。若系统低于支持范围,应先完成 Windows 更新。查看系统架构:
[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture预期输出示例:
X64实际结果也可能是其他受支持架构,应以当前设备输出为准。
下载并安装 Ollama
Windows 推荐使用官方 OllamaSetup.exe 安装程序。操作步骤:
- 从 Ollama 官方下载页面获取 Windows 安装程序。
- 关闭正在运行的旧版 Ollama,避免升级时文件被占用。
- 双击运行
OllamaSetup.exe。 - 按安装程序提示完成安装。
- 从开始菜单启动 Ollama。
- 等待系统托盘出现 Ollama 后台应用。
- 重新打开 PowerShell,让新的
PATH生效。
默认安装不要求管理员权限,并安装到当前用户目录。常见程序目录为:
%LOCALAPPDATA%\Programs\Ollama模型和配置通常位于:
%HOMEPATH%\.ollama不要直接修改程序目录中的运行库。模型目录需要迁移时,应设置 OLLAMA_MODELS,而不是手动移动后继续使用旧路径。
验证命令行
打开新的 PowerShell,执行:
Get-Command ollama
ollama --version预期输出:
CommandType Name Version Source
----------- ---- ------- ------
Application ollama.exe <VERSION> <INSTALL_PATH>
ollama version is <VERSION>实际版本号和安装路径可能不同。验收标准是:
Get-Command能定位到ollama.exe。ollama --version能输出版本号。- 没有出现“无法将 ollama 识别为命令”等错误。
若安装后当前终端仍找不到命令,先关闭终端并重新打开。若仍失败,检查用户 PATH 是否包含 Ollama 安装目录。
验证后台应用
安装版 Ollama 通常会作为登录启动项在后台运行。可使用以下命令检查相关进程:
Get-Process | Where-Object ProcessName -Like "ollama*" |
Select-Object ProcessName, Id, Path预期输出示例:
ProcessName Id Path
----------- -- ----
<PROCESS> <ID> <INSTALL_PATH>进程名称、数量和路径可能随版本变化。只要存在来自 Ollama 安装目录的运行进程,并且后续 API 验证成功,即可判定后台应用正常。如果没有结果:
- 从 Windows 开始菜单启动 Ollama。
- 检查任务管理器的“启动应用”中是否禁用了 Ollama。
- 检查安全软件是否阻止后台程序。
- 查看日志确认启动失败原因。
验证默认端口
Ollama 默认监听本机端口 11434。执行:
Get-NetTCPConnection -LocalPort 11434 -State Listen |
Select-Object LocalAddress, LocalPort, State, OwningProcess预期输出示例:
LocalAddress LocalPort State OwningProcess
------------ --------- ----- -------------
127.0.0.1 11434 Listen <PID>实际监听地址可能以 IPv4 或 IPv6 形式显示。验收标准是存在 Listen 状态的 11434 端口。
若命令返回“未找到匹配对象”,说明当前没有进程监听该端口。此时应先确认 Ollama 后台应用是否启动。
验证本地 API
使用 PowerShell 调用模型列表接口:
$response = Invoke-RestMethod -Method Get -Uri "http://localhost:11434/api/tags"
$response | ConvertTo-Json -Depth 6新安装且尚未下载模型时,预期响应可能是:
{
"models": []
}如果已经下载模型,models 数组中会包含模型信息。验收标准是:
- 请求能够连接。
- 返回内容可以解析为 JSON。
- 顶层包含
models字段。
不要把空数组当作安装失败。空数组只表示本地尚未保存模型。
检查安装目录和模型目录
打开程序目录:
explorer "$env:LOCALAPPDATA\Programs\Ollama"预期结果:
文件资源管理器打开 Ollama 程序目录。打开默认模型与配置目录:
explorer "$HOME\.ollama"预期结果:
文件资源管理器打开当前用户的 .ollama 目录。如果目录尚不存在,先启动 Ollama 或执行一次模型相关操作。目录内容随版本和使用状态变化,不应依赖固定文件数量进行验证。
查看 Windows 日志
打开日志目录:
explorer "$env:LOCALAPPDATA\Ollama"预期结果:
文件资源管理器打开 Ollama 日志目录,可查看 server.log 等文件。最近的服务日志通常位于 server.log,历史日志可能使用带编号的文件名。排查问题时优先查看日志末尾,而不是直接删除全部日志。使用 PowerShell 查看最后 100 行:
Get-Content "$env:LOCALAPPDATA\Ollama\server.log" -Tail 100预期输出:
<最近的 Ollama 服务日志>日志时间、字段和内容取决于实际运行状态。重点搜索端口占用、GPU 发现、模型目录权限和网络下载错误。
修改模型存储位置
当用户目录所在磁盘空间不足时,可以设置用户级环境变量 OLLAMA_MODELS。
示例:把模型目录设置为 D:\OllamaModels。
New-Item -ItemType Directory -Force -Path "D:\OllamaModels" | Out-Null
[Environment]::SetEnvironmentVariable(
"OLLAMA_MODELS",
"D:\OllamaModels",
"User"
)
[Environment]::GetEnvironmentVariable("OLLAMA_MODELS", "User")预期输出:
D:\OllamaModels环境变量不会自动影响已经运行的 Ollama 进程。设置完成后:
- 从系统托盘退出 Ollama。
- 从开始菜单重新启动 Ollama。
- 下载一个测试模型。
- 检查新目录是否产生模型文件。
如果旧目录已有模型,应先备份,再规划迁移。不要在 Ollama 仍运行时同时移动模型文件。
常见安装问题
1. PowerShell 找不到 ollama
故障表现:
ollama : 无法将“ollama”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。排查步骤:
Test-Path "$env:LOCALAPPDATA\Programs\Ollama\ollama.exe"
$env:Path -split ";"预期结果:
True
<PATH_ENTRY_1>
<PATH_ENTRY_2>
...如果文件存在但 PATH 中没有安装目录,重新运行安装程序或修复用户环境变量。
2. 端口 11434 已被占用
检查占用进程:
Get-NetTCPConnection -LocalPort 11434 |
Select-Object State, OwningProcess再查看进程:
Get-Process -Id <PID>预期输出:
Handles NPM(K) PM(K) WS(K) CPU(s) Id ProcessName
------- ------ ----- ----- ------ -- -----------
<VALUES> <PID> <PROCESS_NAME><PID> 替换为第一条命令返回的进程号。确认不是 Ollama 后,再决定停止冲突程序或调整服务配置。
3. 安装后没有后台运行
检查任务管理器中的启动应用,并从开始菜单手动启动 Ollama。若启动后立即退出,查看 server.log。
4. GPU 没有被使用
先确认驱动正常,再运行模型并使用 ollama ps 检查处理器分布。安装成功只表示服务可用,不代表 GPU 一定已启用。
5. 模型下载失败
企业代理环境只应按官方建议配置出站 HTTPS 代理。设置后必须退出并重新启动 Ollama,使环境变量被新进程继承。
本课练习
练习 1:完成四项验证
任务目标:证明 Windows 安装成功。初始条件:已安装并启动 Ollama。
实现要求:依次验证命令路径、版本、端口和 /api/tags。
验收条件:保存四条命令及其实际输出,并说明每条输出证明了什么。
练习 2:修改模型目录
任务目标:把模型存储位置迁移到空间更大的磁盘。初始条件:准备一个新的空目录。
实现要求:设置用户级 OLLAMA_MODELS,重启 Ollama,并下载测试模型验证目录生效。
验收条件:新目录出现模型数据,API 和 CLI 仍能正常工作。
练习 3:模拟 PATH 故障
任务目标:掌握命令不可用的排查顺序。初始条件:假设安装完成,但 PowerShell 找不到 ollama。
实现要求:从程序文件、环境变量、新终端和重新安装四个层次设计排查步骤。验收条件:每一步都有明确的判断结果和下一步动作。