企业官网建设流程全解析

• 云原生
• 后端
• 运维

导读

在 Olares 中，本地大模型以"模型实例"的形式运行：模型文件由推理引擎基座应用负责拉取与校验，推理服务由引擎进程提供。当你在启动台打开模型实例后，模型控制台（Model Console）中的Model状态始终没有变为Ready，或Engine状态始终没有变为Running时，说明模型下载、文件校验或引擎启动链路中某个环节被卡住。本文将以 Olares 模型控制台的状态模型为骨架，分阶段讲解如何定位卡点、修正环境变量与资源配额、释放显存和磁盘空间，并在必要情况下收集日志交由支持渠道分析。读完本文，你将掌握一套可复现的"模型未就绪 / 引擎未运行 / 状态无变化"三级排查流程，并理解MODEL_SOURCE、MODEL_NAME、ENGINE_ARGS、REQUIRED_GPU_MEMORY等关键变量在底层如何决定模型能否正常上线。

模型控制台的两个核心状态

在 Olares 中，一个模型实例能否对外提供服务，取决于两个相互依赖的状态（见 llm-base-apps 监控章节）：

• Model：模型文件是否下载完成并通过校验。文件下载并校验完成后显示Ready。
• Engine：推理服务是否成功启动。推理服务上线后显示Running。

二者的先后关系是确定的：引擎无法为一个文件尚未就绪的模型提供服务。因此排查时必须遵循"先模型、后引擎"的顺序。

第一步：确认卡在哪个阶段

从启动台打开模型实例，在状态（Status）页查看服务状态（Service status）。根据你看到的现象，可以快速判断问题落在哪条链路上：

这张表格对应了两种完全不同的故障域：前者是"文件层"问题（网络、磁盘、来源格式），后者是"进程层"问题（引擎参数、显存配额、应用生命周期）。下面分别处理。

模型未就绪：文件层排查

当Model未显示Ready，按以下顺序排查：

1. 保持模型实例运行并等待。如果模型仍在下载，请勿关闭实例。大型模型文件（尤其是 27B 以上量级的 GGUF 或 safetensors 权重）可能需要较长时间才能下载完成，中途关闭会中断下载。
2. 确认网络可达性与磁盘空间：
   • 确认 Olares 可以访问模型来源（Hugging Face、Ollama 库等）。
   • 确认磁盘有足够可用空间。如果存储空间不足，参考释放 Olares 磁盘空间：先删除不再使用的模型，再谨慎清理未引用的容器镜像（olares-cli doctor images --unused可列出未被标准工作负载引用的镜像）。
3. 核对环境变量格式。如果实例由引擎基座应用创建，请按照对应引擎的格式检查MODEL_SOURCE和MODEL_NAME，详见下文"关键环境变量的格式要求"。
4. 修正后重新应用配置。如果你在设置>应用>[模型应用]>管理环境变量中修正了变量，请保存更改并点击应用（Apply），然后等待模型控制台更新状态。环境变量修改不会即时生效，需要平台重新调度应用后才反映到状态。

重要约束：实例运行期间，请勿删除尚未下载完成的模型文件，否则可能导致应用状态与已存储文件不一致，反而让后续恢复变得更复杂。

引擎未运行：进程层排查

当Model已显示Ready而Engine未显示Running时：

1. 先等待模型就绪。模型文件未就绪时，引擎无法提供模型服务，这是前置条件。
2. 检查实例配置，重点核对三项：
   • MODEL_NAME是否与配置的模型一致。注意MODEL_NAME需要严格遵循对应引擎的命名推导规则（见下文），写错模型名会导致引擎加载不到文件。
   • ENGINE_ARGS是否使用所选引擎要求的语法。不同引擎参数风格完全不同：llama.cpp 使用-c这类短参数，vLLM 使用--max-model-len，SGLang 使用--context-length，Ollama 则通过OLLAMA_*环境变量形式传入。
   • 引擎的REQUIRED_GPU_MEMORY值是否超过可用资源。该值定义了实例启动所需的最小 GPU 显存，如果显存配额不足，调度器无法为实例预留资源。
3. 恢复已停止的应用。如果应用处于已停止状态，请从应用市场>我的 Olares或设置>应用中恢复应用。
4. 处理显存不足。如果 Olares 提示显存不足，参考GPU 应用安装或恢复后处于暂停状态：在显存分片（Olares 1.12.5）或容量切分（Olares 1.12.6）模式下，需要先释放其他应用占用的显存配额，再恢复目标应用。
5. 回到模型控制台确认最终状态。只有Model显示Ready且Engine显示Running后，才能继续连接客户端应用。

关键环境变量的格式要求

模型实例的下载与启动完全由环境变量驱动。以下格式要求来自使用 Ollama、vLLM、llama.cpp 和 SGLang 运行本地大模型的配置章节，排查时请对照自己的实例逐项比对。

llama.cpp 引擎基座（GGUF 文件）

• MODEL_SOURCE：hf://<repo> --include <file>.gguf。如需下载多个文件，用逗号分隔每个条目。示例：模型页面https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF，对应MODEL_SOURCE为hf://unsloth/Qwen3.6-35B-A3B-GGUF --include Qwen3.6-35B-A3B-UD-Q4_K_XL.gguf。
• MODEL_NAME：从MODEL_SOURCE推导，格式为<repo>:<quantization>（每个实例只能带一种量化）。对应上述来源，MODEL_NAME为unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_XL。
• ENGINE_ARGS：上下文长度（-c）为必填项，多个参数用空格分隔。例如-c 65536或-c 65536 -ngl all。
• LLAMACPP_REQUIRED_GPU_MEMORY：实例启动所需的最小 GPU 显存，单位为 MB 或 Gi（如20Gi）。在时间分片或独占模式下设为小于显卡总显存；在显存分片模式下设为小于剩余显存；在 CPU 模式下设为0。

Ollama 引擎基座（模型标签）

• MODEL_SOURCE：ollama://<model>:<size-tag>。示例：ollama://qwen3.5:2b。
• MODEL_NAME：取ollama://之后的字符串，即qwen3.5:2b。
• ENGINE_ARGS：通过 Ollama 环境变量形式传入，如OLLAMA_CONTEXT_LENGTH=8192或OLLAMA_CONTEXT_LENGTH=8192 OLLAMA_KV_CACHE_TYPE=q8_0。
• OLLAMA_REQUIRED_GPU_MEMORY：例如8Gi或8192Mi，规则同 llama.cpp。

vLLM / SGLang 引擎基座（safetensors 权重）

• MODEL_SOURCE：选择包含.safetensors权重文件的仓库，格式为hf://<repo>。示例：hf://Qwen/Qwen3.5-2B。
• MODEL_NAME：取hf://之后的字符串，即Qwen/Qwen3.5-2B。
• ENGINE_ARGS：vLLM 示例--max-model-len 65536，SGLang 示例--context-length 65536。上下文长度为必填项。
• VLLM/SGLANG_REQUIRED_GPU_MEMORY：规则同上。

所有引擎共用MODEL_MODE（Chat 或 Embedding）与MODEL_SUPPORTS（Vision、Tools、Thinking，嵌入模型选 None）两个变量，它们决定该实例在 Router 中暴露的能力类型。若MODEL_MODE选择 Embedding 而引擎按 Chat 模型启动，客户端连接阶段也会出现问题。

状态一直没有变化：进阶处理与日志收集

如果模型和引擎的状态长时间停滞，先注意以下红线：

请勿删除应用命名空间、Application 资源或共享引擎服务。这些操作可能影响其他模型实例，并增加恢复难度。多个模型实例可能共享同一套引擎基座服务，删除共享资源会波及所有实例。

记录必要信息

在寻求支持前，请先记录以下信息：

• Olares 版本和模型应用版本。
• 引擎基座类型，以及该应用是预构建模型还是克隆实例（克隆实例在 Market 或 Settings 中会显示From template标签）。
• Model和Engine的完整状态。
• 模型来源和引擎参数，注意移除令牌或凭据（MODEL_SOURCE中若包含私有仓库，可能含有访问令牌）。
• 问题开始的时间，以及此前刚进行过的更改（例如刚修改过环境变量、更新过 GPU 模式、调整过显存分配）。

导出应用日志

前往应用市场>我的 Olares>日志，下载应用操作日志。应用日志记录了环境变量变更、下载进度、引擎启动命令与失败原因，是定位ENGINE_ARGS语法错误或显存分配失败的关键证据。

收集系统诊断信息

如果需要提供更多上下文，参考收集诊断信息：

1. 通过 SSH 连接到 Olares 主机（Olares One 上 SSH 用户为olares：ssh olares@{local_ip_address}）。
2. 运行sudo olares-cli logs --output-dir "$HOME/olares-logs"，该命令会收集 Olares 系统、Kubernetes、容器、内核和网络的近期诊断信息，并在最后一行输出压缩包完整路径。
3. 如果问题刚发生不久，可加--since 3h等时间范围参数减小压缩包体积。
4. 使用scp olares@{local_ip_address}:~/olares-logs/olares-logs-{timestamp}.tar.gz .下载到本地，再通过私密支持渠道共享日志压缩包。

相关指南

• 使用 Ollama、vLLM、llama.cpp 和 SGLang 运行本地大模型——引擎基座应用的选择、实例创建与环境变量完整配置。
• 连接 AI 应用与模型服务——模型就绪后，客户端如何通过 Router 连接本地模型。
• GPU 应用安装或恢复后处于暂停状态——显存分片/容量切分模式下释放显存的具体操作。
• 内存不足或没有释放——暂停应用后内存未释放时的处理方式。
• 释放 Olares 磁盘空间——删除不再使用的模型与未引用容器镜像。
• 收集诊断信息——使用olares-cli logs收集系统日志。

• 云原生
• 后端
• 运维