大模型应用开发 / 系统课时

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 版本:

powershell
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion, OsBuildNumber

预期输出:

text
WindowsProductName    WindowsVersion    OsBuildNumber
------------------    --------------    -------------
<WINDOWS_EDITION>     <VERSION>         <BUILD_NUMBER>

<WINDOWS_EDITION>、<VERSION> 和 <BUILD_NUMBER> 取决于当前系统。若系统低于支持范围,应先完成 Windows 更新。查看系统架构:

powershell
[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture

预期输出示例:

text
X64

实际结果也可能是其他受支持架构,应以当前设备输出为准。

下载并安装 Ollama

Windows 推荐使用官方 OllamaSetup.exe 安装程序。操作步骤:

  1. 从 Ollama 官方下载页面获取 Windows 安装程序。
  2. 关闭正在运行的旧版 Ollama,避免升级时文件被占用。
  3. 双击运行 OllamaSetup.exe。
  4. 按安装程序提示完成安装。
  5. 从开始菜单启动 Ollama。
  6. 等待系统托盘出现 Ollama 后台应用。
  7. 重新打开 PowerShell,让新的 PATH 生效。

默认安装不要求管理员权限,并安装到当前用户目录。常见程序目录为:

text
%LOCALAPPDATA%\Programs\Ollama

模型和配置通常位于:

text
%HOMEPATH%\.ollama

不要直接修改程序目录中的运行库。模型目录需要迁移时,应设置 OLLAMA_MODELS,而不是手动移动后继续使用旧路径。

验证命令行

打开新的 PowerShell,执行:

powershell
Get-Command ollama
ollama --version

预期输出:

text
CommandType    Name        Version    Source
-----------    ----        -------    ------
Application    ollama.exe  <VERSION>  <INSTALL_PATH>

ollama version is <VERSION>

实际版本号和安装路径可能不同。验收标准是:

  • Get-Command 能定位到 ollama.exe。
  • ollama --version 能输出版本号。
  • 没有出现“无法将 ollama 识别为命令”等错误。

若安装后当前终端仍找不到命令,先关闭终端并重新打开。若仍失败,检查用户 PATH 是否包含 Ollama 安装目录。

验证后台应用

安装版 Ollama 通常会作为登录启动项在后台运行。可使用以下命令检查相关进程:

powershell
Get-Process | Where-Object ProcessName -Like "ollama*" |
    Select-Object ProcessName, Id, Path

预期输出示例:

text
ProcessName    Id       Path
-----------    --       ----
<PROCESS>      <ID>     <INSTALL_PATH>

进程名称、数量和路径可能随版本变化。只要存在来自 Ollama 安装目录的运行进程,并且后续 API 验证成功,即可判定后台应用正常。如果没有结果:

  1. 从 Windows 开始菜单启动 Ollama。
  2. 检查任务管理器的“启动应用”中是否禁用了 Ollama。
  3. 检查安全软件是否阻止后台程序。
  4. 查看日志确认启动失败原因。

验证默认端口

Ollama 默认监听本机端口 11434。执行:

powershell
Get-NetTCPConnection -LocalPort 11434 -State Listen |
    Select-Object LocalAddress, LocalPort, State, OwningProcess

预期输出示例:

text
LocalAddress    LocalPort    State     OwningProcess
------------    ---------    -----     -------------
127.0.0.1       11434        Listen    <PID>

实际监听地址可能以 IPv4 或 IPv6 形式显示。验收标准是存在 Listen 状态的 11434 端口。

若命令返回“未找到匹配对象”,说明当前没有进程监听该端口。此时应先确认 Ollama 后台应用是否启动。

验证本地 API

使用 PowerShell 调用模型列表接口:

powershell
$response = Invoke-RestMethod -Method Get -Uri "http://localhost:11434/api/tags"
$response | ConvertTo-Json -Depth 6

新安装且尚未下载模型时,预期响应可能是:

json
{
  "models": []
}

如果已经下载模型,models 数组中会包含模型信息。验收标准是:

  • 请求能够连接。
  • 返回内容可以解析为 JSON。
  • 顶层包含 models 字段。

不要把空数组当作安装失败。空数组只表示本地尚未保存模型。

检查安装目录和模型目录

打开程序目录:

powershell
explorer "$env:LOCALAPPDATA\Programs\Ollama"

预期结果:

text
文件资源管理器打开 Ollama 程序目录。

打开默认模型与配置目录:

powershell
explorer "$HOME\.ollama"

预期结果:

text
文件资源管理器打开当前用户的 .ollama 目录。

如果目录尚不存在,先启动 Ollama 或执行一次模型相关操作。目录内容随版本和使用状态变化,不应依赖固定文件数量进行验证。

查看 Windows 日志

打开日志目录:

powershell
explorer "$env:LOCALAPPDATA\Ollama"

预期结果:

text
文件资源管理器打开 Ollama 日志目录,可查看 server.log 等文件。

最近的服务日志通常位于 server.log,历史日志可能使用带编号的文件名。排查问题时优先查看日志末尾,而不是直接删除全部日志。使用 PowerShell 查看最后 100 行:

powershell
Get-Content "$env:LOCALAPPDATA\Ollama\server.log" -Tail 100

预期输出:

text
<最近的 Ollama 服务日志>

日志时间、字段和内容取决于实际运行状态。重点搜索端口占用、GPU 发现、模型目录权限和网络下载错误。

修改模型存储位置

当用户目录所在磁盘空间不足时,可以设置用户级环境变量 OLLAMA_MODELS。

示例:把模型目录设置为 D:\OllamaModels。

powershell
New-Item -ItemType Directory -Force -Path "D:\OllamaModels" | Out-Null
[Environment]::SetEnvironmentVariable(
    "OLLAMA_MODELS",
    "D:\OllamaModels",
    "User"
)
[Environment]::GetEnvironmentVariable("OLLAMA_MODELS", "User")

预期输出:

text
D:\OllamaModels

环境变量不会自动影响已经运行的 Ollama 进程。设置完成后:

  1. 从系统托盘退出 Ollama。
  2. 从开始菜单重新启动 Ollama。
  3. 下载一个测试模型。
  4. 检查新目录是否产生模型文件。

如果旧目录已有模型,应先备份,再规划迁移。不要在 Ollama 仍运行时同时移动模型文件。

常见安装问题

1. PowerShell 找不到 ollama

故障表现:

text
ollama : 无法将“ollama”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

排查步骤:

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

预期结果:

text
True
<PATH_ENTRY_1>
<PATH_ENTRY_2>
...

如果文件存在但 PATH 中没有安装目录,重新运行安装程序或修复用户环境变量。

2. 端口 11434 已被占用

检查占用进程:

powershell
Get-NetTCPConnection -LocalPort 11434 |
    Select-Object State, OwningProcess

再查看进程:

powershell
Get-Process -Id <PID>

预期输出:

text
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。

实现要求:从程序文件、环境变量、新终端和重新安装四个层次设计排查步骤。验收条件:每一步都有明确的判断结果和下一步动作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Windows 安装与环境验证

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通