Ollama 使用环境变量

glmos-code-explain# Ollama 环境变量设置

Ollama 使用环境变量来配置其行为，这包括模型文件的存储位置、运行时目录、网络设置、性能调优等。通过设置这些变量，您可以根据自己的需求和环境自定义 Ollama 的运行方式。

快速参考：常用环境变量

环境变量 描述 默认值 (可能因系统/安装方式而异) 示例值
OLLAMA_MODELS (最常用) 指定模型存储目录的路径 (blobs 和 manifests) Linux (systemd):/usr/share/ollama/.ollama/models
Linux (user): ~/.ollama/models
macOS: ~/.ollama/models
Windows: %USERPROFILE%\.ollama\models		 /data/ollama_models 或 D:\OllamaModels
OLLAMA_HOST 设置 Ollama 服务监听的网络地址和端口 127.0.0.1:11434 (仅本地) 0.0.0.0:11434 (所有接口)
OLLAMA_ORIGINS 配置允许访问 Ollama API 的跨域来源 (CORS)，逗号分隔 http://localhost, http://localhost:*, http://127.0.0.1, http://127.0.0.1:*, app://* http://yourapp.com,http://localhost:8080
OLLAMA_KEEP_ALIVE 控制模型在内存中保持活动状态的时间 (单位: s, m, h; -1=永久) 5m 30m 或 -1
OLLAMA_MAX_LOADED_MODELS 可同时加载到内存/显存的最大模型数量 视 GPU 数量或 CPU 推理而定 (如1) 3
OLLAMA_NUM_PARALLEL 每个已加载模型可同时处理的并行请求数 未明确指定，依赖内部逻辑 4
OLLAMA_MAX_QUEUE 请求队列的最大长度，超出时返回 503 错误 512 1024
OLLAMA_FLASH_ATTENTION (实验性) 启用 Flash Attention 优化 (若 GPU 支持) 0 (禁用) 1 (启用)
OLLAMA_KV_CACHE_TYPE 设置键/值缓存的量化类型以减少内存占用 f16 q8_0 或 q4_0
OLLAMA_DEBUG 启用调试模式，增加日志输出 未启用 (0) 1 (启用)
HTTPS_PROXY 设置用于下载模型的 HTTPS 代理服务器地址 无 https://user:pass@proxy.example.com:8080
OLLAMA_RUNNERS_DIR (较少用) 指定查找和存储 Runner 二进制文件的目录 通常由 Ollama 内部管理 /path/to/custom/ollama_runners

详细说明

核心路径变量

OLLAMA_MODELS

  • 作用: 指定 Ollama 存储下载的模型文件（blobs 和 manifests）的根目录。这是最重要的路径配置变量。
  • 默认值:
    • Linux: /usr/share/ollama/.ollama/models (当作为 systemd 服务运行时) 或 ~/.ollama/models (当作为当前用户运行时)。
    • macOS: ~/.ollama/models
    • Windows: C:\Users\<username>\.ollama\models (即 %USERPROFILE%\.ollama\models)
  • 用途: 如果你想将模型存储在不同的磁盘驱动器或自定义位置（例如，一个具有更大空间的外部硬盘），必须设置此变量。
  • 示例:
    • Linux/macOS (bash/zsh): export OLLAMA_MODELS=/path/to/your/ollama_models
    • Windows (CMD): set OLLAMA_MODELS=D:\ollama_models
    • Windows (PowerShell): $env:OLLAMA_MODELS = "D:\ollama_models"

OLLAMA_RUNNERS_DIR

  • 作用: (较少使用) 指定 Ollama 查找和存储其运行时（runners）二进制文件的目录，这些运行时用于执行模型（特别是 GPU 加速相关的）。
  • 默认值: 通常位于 Ollama 安装目录下或者其内部管理的路径中，对普通用户透明。
  • 用途: 主要用于开发或特殊部署场景，例如当你需要使用自定义编译的 runner 时。普通用户一般不需要设置此变量。
  • 示例:
    • Linux/macOS (bash/zsh): export OLLAMA_RUNNERS_DIR=/path/to/custom/ollama_runners

网络配置变量

OLLAMA_HOST

  • 作用: 指定 Ollama 服务监听的网络地址和端口。
  • 默认值: 127.0.0.1:11434 (仅监听本地回环地址)
  • 用途:
    • 允许其他设备访问 Ollama 服务 (例如设置为 0.0.0.0:11434 监听所有网络接口)。
    • 更改监听端口以避免冲突。
  • 示例:
    • Linux/macOS (bash/zsh): export OLLAMA_HOST=0.0.0.0:11434
    • Windows (CMD): set OLLAMA_HOST=192.168.1.100:11434

OLLAMA_ORIGINS

  • 作用: 配置允许访问 Ollama API 的跨域来源 (CORS)。这对于从 Web 浏览器或其他不同域名的客户端访问 API至关重要。
  • 默认值: http://localhost, http://localhost:*, http://127.0.0.1, http://127.0.0.1:*, app://*
  • 用途: 如果你的 Web 应用或其他客户端从不同的域名或端口访问 Ollama API，需要将这些来源添加到这里，使用逗号分隔多个值。可以使用 * 作为通配符。
  • 示例:
    • Linux/macOS (bash/zsh): export OLLAMA_ORIGINS=http://yourapp.com,http://localhost:8080,*

性能与行为配置

  • OLLAMA_KEEP_ALIVE: 控制模型在没有收到请求后在内存中保持加载状态的时长。设置为 -1 表示永不卸载，0 表示立即卸载。适合内存/显存充足且希望快速响应后续请求的场景。
  • OLLAMA_MAX_LOADED_MODELS: 限制同时可以加载到内存/显存中的模型数量。有助于管理资源消耗，防止内存溢出。
  • OLLAMA_NUM_PARALLEL: 控制单个模型实例能并行处理多少个传入请求。增加此值可以提高吞吐量，但也会增加资源使用。
  • OLLAMA_MAX_QUEUE: Ollama 服务器在返回“服务器繁忙”（503）错误之前可以排队的请求数量。
  • OLLAMA_FLASH_ATTENTION: (实验性) 如果你的 GPU 支持 Flash Attention，启用此项 (1) 可以显著减少推理过程中的内存使用并可能提高速度。
  • OLLAMA_KV_CACHE_TYPE: 设置 K/V 缓存的量化类型（如 q8_0, q4_0），以牺牲少量精度为代价减少内存（主要是显存）占用。默认 f16 (半精度浮点)。

其他配置

  • OLLAMA_DEBUG: 设置为 1 会启用详细的调试日志输出，有助于排查问题。
  • HTTPS_PROXY: 如果你需要通过 HTTPS 代理服务器下载模型，设置此变量。

相关的系统环境变量

Ollama 的行为也可能受到标准系统环境变量的影响：

  • HOME / USERPROFILE: 定义用户的主目录。Ollama 使用它来确定默认的 .ollama 配置和模型存储目录。注意: 不建议通过修改 HOME 来改变 Ollama 路径，应优先使用 OLLAMA_MODELS。
  • TMPDIR / TEMP / TMP: 指定操作系统用于存储临时文件的目录。Ollama 在模型下载或某些操作期间可能会使用。如果默认临时目录空间不足，修改此系统变量可能会有帮助。
  • PATH: 定义系统查找可执行文件的目录列表。确保 ollama 命令本身能被系统找到（安装程序通常会处理）。
  • LD_LIBRARY_PATH (Linux) / DYLD_LIBRARY_PATH (macOS): 指定动态链接器查找共享库的额外路径。对于 GPU 加速，如果 CUDA 或 ROCm 库未在标准路径，可能需要设置此变量。

如何设置环境变量

环境变量的设置方式取决于你的操作系统和使用场景（临时或永久）。

Linux / macOS

  • 临时设置 (当前 Shell 会话有效):

    1
    2
    3
    4
    5
    export OLLAMA_MODELS=/data/ollama_models
    export OLLAMA_HOST=0.0.0.0:11434
    # 启动 Ollama 服务或运行命令
    ollama serve & 
    # 或者 ollama run modelname

  • 永久设置 (用户级别):
    将 export VAR_NAME=value 添加到你的 Shell 配置文件中，例如：

    • Bash: ~/.bashrc 或 ~/.profile
    • Zsh: ~/.zshrc
      然后运行 source ~/.bashrc (或相应文件) 或重新打开终端使设置生效。

  • 永久设置 (Systemd 服务, 适用于 Linux):
    如果 Ollama 作为 systemd 服务运行，需要修改服务单元文件：

    1. 运行 sudo systemctl edit ollama.service
    2. 在打开的编辑器中添加以下内容（替换 VAR_NAME 和 value）：
      1
      2
      3
      [Service]
      Environment="VAR_NAME=value"
      Environment="ANOTHER_VAR=another_value"
    3. 保存并关闭编辑器。
    4. 重新加载 systemd 配置并重启服务：
      1
      2
      sudo systemctl daemon-reload
      sudo systemctl restart ollama

Windows

  • 临时设置 (当前命令提示符 CMD 会话):

    1
    2
    3
    set OLLAMA_MODELS=D:\OllamaModels
    set OLLAMA_HOST=0.0.0.0:11434
    ollama serve

  • 临时设置 (当前 PowerShell 会话):

    1
    2
    3
    $env:OLLAMA_MODELS = "D:\OllamaModels"
    $env:OLLAMA_HOST = "0.0.0.0:11434"
    ollama serve

  • 永久设置:

    1. 在 Windows 搜索栏中搜索“环境变量”。
    2. 点击“编辑系统环境变量”。
    3. 在“系统属性”窗口的“高级”选项卡下，点击“环境变量…”按钮。
    4. 在“用户变量”或“系统变量”区域（推荐用户变量，除非需要对所有用户生效），点击“新建…”。
    5. 输入变量名 (例如 OLLAMA_MODELS) 和变量值 (例如 D:\OllamaModels)。
    6. 点击“确定”关闭所有窗口。
    7. 重要: 需要重新启动任何已经打开的 CMD 或 PowerShell 窗口，以及 Ollama 服务（如果正在运行），才能使新的永久环境变量生效。对于图形界面的 Ollama 应用，可能需要重启应用甚至注销/重新登录。

总结

理解和使用 Ollama 的环境变量，特别是 OLLAMA_MODELS 用于指定模型存储位置，以及 OLLAMA_HOST 和 OLLAMA_ORIGINS 用于网络配置，是有效管理和部署 Ollama 的关键。根据你的具体需求调整这些设置可以优化性能、管理资源并集成到现有工作流中。