本地运行与测试大模型¶

本地运行大模型的价值不是替代 Kubernetes，而是缩短开发反馈环：先在笔记本或单台工作站上验证模型是否能加载、Prompt 是否有效、API 是否兼容、RAG 与 Tool Calling 是否正确，再把同一套契约放到 GPU 服务器和 Kubernetes 上做容量、性能与可靠性验证。

对于第一次尝试，优先使用 Ollama；需要图形界面时用 LM Studio；需要直接控制 GGUF、线程和显存卸载时用 llama.cpp；Apple Silicon 上做原生实验可用 MLX-LM；需要多模态、多后端统一 API 时评估 LocalAI；需要模拟数据中心高并发服务时直接使用 vLLM 或 SGLang。

1. 本地测试能回答什么¶

适合在本地验证：

• 模型、量化版本和 Chat Template 能否正常工作；
• Prompt、System Prompt、停止词和结构化输出是否符合预期；
• OpenAI-Compatible API、流式响应、Embedding 和 Tool Calling 契约；
• RAG 检索、上下文拼装、Agent 工具参数和错误处理；
• 模型下载、加载、首 Token 和单请求生成速度；
• 应用能否只修改 base_url 和模型名就在不同 Runtime 间切换。

不能直接从本地结果推导：

• 多用户并发下的 TTFT、TPOT、吞吐和尾延迟；
• 多 GPU Tensor/Expert Parallel、RDMA 和拓扑效率；
• 连续批处理、KV Cache、Prefix Cache 和请求调度效果；
• Pod 重启、滚动发布、扩缩容、节点故障和流量切换行为；
• 生产硬件上的显存容量、单位 Token 成本和 SLO。

因此，本地验证通过表示“功能基线成立”，不表示“生产容量已经验证”。

2. 工具怎么选¶

“OpenAI-Compatible”只代表兼容一部分请求与响应协议，不保证 Tool Calling、JSON Schema、Responses API、Embedding、Usage、错误码和流式事件完全相同。应用必须有自己的 API 契约测试。

3. 先看硬件和模型大小¶

模型运行内存至少包括：

权重 + KV Cache + Runtime Workspace + 输入/输出缓冲 + 系统保留

仅按参数量估算权重下限：

权重字节 ≈ 参数量 × 每参数位数 ÷ 8

例如 7B 模型的纯 4-bit 权重理论下限约为 3.5 GB，但文件元数据、量化分组、Runtime、KV Cache 和上下文都会继续占用内存。不要用模型文件大小直接当作运行内存。

本地起步建议：

1. 先选择 1B～4B 的 Instruct 模型验证流程，再尝试 7B～8B 量化模型。
2. Apple Silicon 的 CPU/GPU 使用统一内存，仍要给操作系统和应用留足空间。
3. NVIDIA/AMD 机器同时观察显存、系统内存和是否发生 CPU/GPU 混合卸载。
4. 上下文越长，KV Cache 通常越大；不要一开始就把 Context 拉到模型上限。
5. 下载前确认模型许可证、用途限制、上下文长度、Chat Template 和量化来源。

4. Ollama：默认入门路径¶

Ollama 支持 macOS、Windows 和 Linux。桌面系统可从官方下载页安装；Linux 可按官方安装文档部署。服务默认监听 127.0.0.1:11434。

1. 拉取并运行模型¶

ollama pull gemma3:4b
ollama run gemma3:4b

常用管理命令：

ollama list
ollama ps
ollama stop gemma3:4b

ollama ps 可以看到模型是在 CPU、GPU 还是混合方式运行。模型名称和可用 Tag 应以 Ollama Model Library 当前页面为准。

2. 调用原生 API¶

Ollama 原生 API 的 Base URL 是 http://localhost:11434/api：

curl http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemma3:4b",
    "stream": false,
    "messages": [
      {"role": "user", "content": "用三句话解释 Kubernetes 调度器"}
    ]
  }'

3. 复用 OpenAI-Compatible 客户端¶

把应用的 Base URL 指向 http://localhost:11434/v1：

curl http://localhost:11434/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemma3:4b",
    "stream": false,
    "messages": [
      {"role": "system", "content": "你是 Kubernetes 平台助手。"},
      {"role": "user", "content": "Pending Pod 应先检查什么？"}
    ]
  }'

不少 SDK 要求 API Key 非空，即使本地 Ollama 不校验它，也可以给一个仅用于客户端校验的占位值：

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama-local

不要把这个占位值误当成服务端认证。Ollama 默认只绑定 Loopback；如果通过 OLLAMA_HOST 改为局域网地址，必须在前面增加认证代理、防火墙和 TLS。

4. 用 Modelfile 固化测试参数¶

Modelfile 可以固定基础模型、System Prompt 和上下文等参数：

FROM gemma3:4b
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
SYSTEM 你是 AI 基础设施助手；不确定时明确说明，不编造命令结果。

在 Modelfile 所在目录执行：

ollama create aik8s-assistant
ollama run aik8s-assistant

Ollama 也支持通过 Modelfile 导入受支持的 Safetensors 目录或 GGUF 文件。它适合本地复现，但进入生产供应链后还应记录原始仓库 Revision、文件 Digest、Tokenizer、Chat Template、量化方法和许可证，不能只保存一个本地模型别名。

5. llama.cpp：直接验证 GGUF¶

llama.cpp 适合 CPU、Apple Silicon、消费级 GPU 和边缘设备，也适合排查 Ollama 抽象之下的 GGUF、Chat Template、线程和 GPU Offload 问题。

安装后可以直接从 Hugging Face 拉取受支持的 GGUF：

llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

启动内置服务：

llama-server -hf ggml-org/gemma-3-1b-it-GGUF \
  --host 127.0.0.1 \
  --port 8080 \
  -c 4096

然后调用 OpenAI-Compatible Endpoint：

curl http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-model",
    "messages": [{"role": "user", "content": "解释 GGUF 的用途"}]
  }'

调优时记录模型文件 Digest、量化格式、Context、Batch、线程数和 GPU Offload 层数，否则两次结果无法公平比较。参考：llama.cpp README 与 llama-server 文档。

6. LM Studio：图形界面与本地 API¶

LM Studio 适合通过 GUI 搜索、下载和试用模型，也可以用 lms 管理模型和服务：

lms get ibm/granite-4-micro
lms load ibm/granite-4-micro
lms server start
curl http://localhost:1234/v1/models

默认服务地址是 http://localhost:1234，可提供自身 REST API 以及 OpenAI/Anthropic-Compatible Endpoint。Linux 无桌面环境时可以使用 llmster 后台服务。

LM Studio 默认不要求认证，也默认只监听 127.0.0.1。启用 --bind 0.0.0.0 或 CORS 前，应先配置 API Token、来源限制和防火墙。参考：LM Studio Local Server 与 lms server start。

7. Apple Silicon 与多后端选择¶

MLX-LM¶

MLX-LM 是 Apple MLX 项目上的 LLM 工具，适合 Apple Silicon 上的生成、对话、量化和轻量微调：

pip install mlx-lm
mlx_lm.chat --model mlx-community/Llama-3.2-3B-Instruct-4bit

它可以帮助确认 Apple 统一内存下的模型可用性和交互速度。若应用依赖稳定的 HTTP 契约，优先让 Ollama、llama.cpp 或 LM Studio 提供服务端；如果直接使用 MLX-LM Server，也要把它视为开发测试服务并单独验证安全与并发边界。参考：MLX-LM。

LocalAI¶

LocalAI 适合希望用一个本地服务统一测试文本、Embedding、图像或音频等多种 Backend 的场景。CPU 容器的最小启动方式为：

docker run --name local-ai -p 127.0.0.1:8080:8080 \
  localai/localai:latest

打开 http://localhost:8080 后可通过 Web UI 安装模型，也可以调用 OpenAI-Compatible API：

curl http://localhost:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3-4b",
    "messages": [{"role": "user", "content": "你好"}]
  }'

GPU 镜像和设备参数取决于 NVIDIA、AMD、Intel 或 Vulkan Backend，必须按照目标版本文档选择。对外暴露时至少启用 API Key 或用户认证。参考：LocalAI Quickstart。

8. 用 vLLM/SGLang 做生产前复测¶

如果最终会部署到 Kubernetes，不要只测 Ollama。准备一台与生产同代或接近的 GPU 服务器，使用生产候选的 Runtime 镜像、模型 Revision 和参数再测一次。

vLLM 的单机概念示例：

vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --host 127.0.0.1 \
  --port 8000 \
  --served-model-name test-model

SGLang 同样提供 OpenAI-Compatible Server，适合共享长前缀、结构化生成和复杂推理程序的候选验证。两者都应以目标版本的官方文档和 SGLang 文档为准，不要把其他版本的启动参数直接复制进生产。

生产前复测至少加入：

• 与真实流量接近的输入/输出 Token 分布；
• 冷启动与模型已加载两种情况；
• 1、2、4、8、16 等逐级并发；
• 流式请求、取消、超时、超长输入和错误请求；
• TTFT、TPOT、端到端延迟、吞吐、显存和 GPU 利用率；
• Tool Calling、结构化输出、Embedding 和多模态等真实功能；
• Runtime 重启、模型切换和客户端重试。

9. 一套可复用的验证流程¶

第一步：定义固定测试样本¶

不要只在聊天窗口凭感觉比较。准备版本化数据集，至少包含：

• 中文、英文、代码和业务术语；
• 短 Prompt、长 Prompt 和多轮对话；
• 正常请求、边界请求和恶意输入；
• Tool Calling、JSON 输出与 RAG 引用；
• 期望结果、允许差异和评分方法。

第二步：建立协议契约测试¶

对每个候选 Runtime 检查：

GET  /v1/models
POST /v1/chat/completions
POST /v1/embeddings        # 如果应用需要
流式事件与 [DONE]
Tool Calling 参数与结果
错误码、超时与取消
usage/token 统计

模型名、API Key 和 Base URL 应由配置注入，不要写死在业务代码中。

第三步：记录可比较结果¶

每次结果都绑定：

模型仓库与 Revision / 文件 Digest
Tokenizer 与 Chat Template
量化格式
Runtime 与版本
硬件、驱动和系统版本
Context、Batch、并行和 Cache 参数
测试数据集版本与并发分布

第四步：切到集群环境复测¶

应用代码保持不变，只替换 Endpoint、认证和模型名。随后用性能基准、压测与回归验证并发，用模型制品、分发与缓存验证冷启动和模型分发，用LLM 推理性能优化调整 Runtime。

10. 从本地到 Kubernetes 的映射¶

Ollama 也可以容器化并运行在 Kubernetes 上，但“能运行”与“适合大规模在线服务”是两个问题。生产选型仍需比较批处理、Cache、并行、指标、滚动升级和目标负载下的单位成本。

11. 安全与数据边界¶

• 默认只监听 Loopback，不要为了手机或同事访问就直接绑定 0.0.0.0。
• 必须远程访问时，增加身份认证、TLS、防火墙、请求大小限制和审计。
• 本地运行减少了 Prompt 发往第三方 API 的需求，但模型下载、更新检查和依赖安装仍可能访问网络。
• 不可信模型、Tokenizer、自定义代码和 Adapter 都属于供应链输入；优先使用无需执行远程代码的格式，并校验来源与 Digest。
• Agent 工具权限与模型是否本地无关。Shell、浏览器、文件和凭据仍应最小授权并置于沙箱。
• 不要把生产密钥、客户原始数据或敏感日志放入未受管控的个人模型目录和测试数据集。

12. 最短落地路径¶

1. 用 Ollama 启动一个 1B～4B Instruct 模型。
2. 通过 /v1/chat/completions 接入应用，完成 Prompt、RAG 和 Tool Calling 功能验证。
3. 建立固定样本和 API 契约测试，记录模型、Runtime 与硬件信息。
4. 在单台目标 GPU 服务器上切换到 vLLM 或 SGLang，保持同一套客户端测试。
5. 用真实 Token 分布与并发做压测，确定显存、Batch、Context 和副本基线。
6. 再部署到 Kubernetes，补齐模型分发、网关、弹性、观测、安全和故障演练。

这条路径把“模型能回答”与“平台能稳定服务”拆开验证，能显著减少一上来就在集群里反复下载大模型、调试 API 和消耗 GPU 的成本。

官方资料¶

• Ollama API Introduction
• Ollama OpenAI Compatibility
• Ollama Modelfile Reference
• llama.cpp
• LM Studio Local Server
• MLX-LM
• LocalAI Quickstart
• vLLM Documentation
• SGLang Documentation