云端 API 省去了推理基础设施管理,本地运行时则让团队直接控制选定的模型文件和推理位置。Ollama 现在同时支持两条路径,因此只看到产品名称还不能判断推理发生在哪里。本地磁盘、日志、模型下载、操作人员、工具、备份、云模型和远程回退都属于数据流与威胁模型。
直接回答: Ollama 是面向开发者的模型运行与分发层,支持受支持的大语言模型(LLM)。它既能通过本地服务执行已下载模型,也能让已登录客户端调用云模型,还可直接向 ollama.com 发起带鉴权的云请求。CLI、Modelfile、原生 /api 和兼容接口降低了集成成本,但团队仍需明确推理位置、身份、授权、数据处理、容量与回滚。
明确区分本地与云端执行
Ollama 在不同信任边界上提供相似的请求结构,必须把实际路径写入系统契约:
| 路径 | Endpoint | 鉴权 | 推理位置 |
|---|---|---|---|
| 本地服务执行本地模型 | http://localhost:11434/api |
API 不鉴权 | 运行 Ollama 的本地主机 |
| 已登录本地服务调用云模型 | 本地 /api 与 :cloud 模型名 |
Ollama 服务端账号登录 | Ollama 云端 |
| 直连原生云 API | https://ollama.com/api |
Authorization: Bearer <API key> |
Ollama 云端 |
| 直连 OpenAI 兼容云 API | https://ollama.com/v1 |
Authorization: Bearer <API key> |
Ollama 云端 |
| 直连 Anthropic 兼容云 API | https://ollama.com/v1/messages |
Bearer Token;仅有 x-api-key 不生效 |
Ollama 云端 |
本地 Daemon 不校验 API Key,SDK 语法要求的占位 Key 不是访问控制。直连云 API 则必须使用 Ollama API Key,并禁止把 Key 放入浏览器代码、源码和日志。兼容端点只实现文档声明的子集,因此消息字段、流式事件、工具行为和错误映射都要逐项测试。严格要求仅本地运行的团队应关闭云功能并验证出站流量,而不是因为 Base URL 指向本机就假设选中的模型一定本地执行。
| Ollama 较适合的场景 | 应评估其他服务层的场景 |
|---|---|
| 开发者或小团队需要可重复的本地模型评测 | 高并发、连续批处理或严格吞吐 SLO 是首要目标 |
| 离线能力和本地模型文件控制是明确要求 | 需要托管控制面、全球弹性伸缩或供应商运营的控制措施 |
| 简洁 CLI、Modelfile 与应用 API 能降低配置成本 | 必须具备成熟的租户隔离、配额、审计和集群调度 |
| 团队可以对指定模型、上下文、并发和设备进行实测 | 希望在测试前得到与硬件无关的容量承诺 |
本地运行时如何工作
对于本地模型,Ollama 先解析模型文件,再通过受支持的后端加载模型、应用 Prompt 模板和运行参数,最后通过 API 流式或一次性返回结果。云模型走的是远程数据路径。无论选择哪条路径,外围应用仍负责身份、策略、校验、持久化与业务动作。
一次请求包含五个可观测阶段:
- 模型解析:Ollama 查找已拉取的模型 Tag,或者读取
FROM、ADAPTER声明的本地模型与适配器。 - 模型加载:运行时在 CPU、GPU 或当前平台支持的混合模式下分配权重和上下文。
- Prompt 构造:模型模板组合系统消息、对话与运行参数。
- 推理生成:
/api/generate面向单次 Prompt;/api/chat面向消息历史,还可以携带工具或结构化输出 Schema。 - 结果处理:最终响应包含计数与耗时字段,可供应用记录;生成文本和工具参数始终是不可信输入。
如果团队能够控制集成,原生 API 的边界最清晰:
| 接口 | 适用任务 | 必须验证的边界 |
|---|---|---|
/api/chat |
多轮消息、工具定义、结构化输出 | 模型支持、工具循环、Schema 校验、流式行为 |
/api/generate |
Prompt 补全、代码中间补全、请求指标 | Prompt 模板、keep_alive、停止条件、流式行为 |
/api/embed |
为检索生成单条或批量 Embedding | 建库和查询必须使用同一 Embedding 模型 |
ollama ps |
查看已加载模型、处理器位置、上下文和过期时间 | 观察实际部署主机,不能只根据模型大小推断 |
/v1 兼容路由 |
复用受支持的 OpenAI 客户端操作 | 参数、错误、功能与未来行为并非无条件等价 |
用 Modelfile 固化可复现配置
Modelfile 记录基础模型、最低运行时版本、Prompt 行为、适配器和推理参数,使实验配置能够随模型交付。它可以改善复现性,但不能执行授权,也不能保证模型生成的数据有效。
下面的 Code Review 示例刻意把 Prompt 指引与输出约束分开:
# 请替换为团队实际验证过的版本与模型文件。
REQUIRES 0.14.0
FROM llama3.2:3b
PARAMETER temperature 0
PARAMETER num_ctx 4096
PARAMETER num_predict 512
SYSTEM """
审查输入代码中的 Bug、安全缺陷与性能风险,并返回简洁的问题列表。
调用方应用负责定义和校验 JSON Schema;不要调用工具或执行外部动作。
"""
保存为 CodeReviewer.modelfile 后,创建本地模型并检查解析后的配置:
ollama create code-reviewer -f ./CodeReviewer.modelfile
ollama show --modelfile code-reviewer
ollama run code-reviewer
受控环境至少应记录 Ollama 版本、模型 Tag、解析后的 Modelfile、模型来源与许可证、主机和驱动信息,以及测试集版本。即使应用代码没有变化,移动模型 Tag 或升级运行时也属于部署变更。
导入 GGUF 模型与适配器
Ollama 可以服务受支持的 GGUF 文件与适配器,但它不是通用训练框架。应使用合适的框架完成训练或微调,导出受支持的文件,再核对转换过程、Tokenizer、Prompt 模板、许可证和质量。
FROM ./my-reviewed-model.gguf
# 适配器必须与训练时使用的基础模型匹配。
ADAPTER ./my-reviewed-adapter.gguf
如果适配器和基础模型不一致,行为可能异常。基础模型、适配器、转换命令和评测结果应归入同一份模型发布记录。
用结构化输出约束格式,而不是信任模型
Ollama 结构化输出可以让原生 Chat 或 Generate API 按 JSON 模式或指定 JSON Schema 返回内容。格式合规更便于解析,但字段值仍可能错误、危险或越权,因此必须同时校验结构与业务语义。
原生接口可以在 format 中直接接收 JSON Schema:
curl -s http://localhost:11434/api/chat \
-H "Content-Type: application/json" \
-d '{
"model": "code-reviewer",
"messages": [{
"role": "user",
"content": "审查:function add(a, b) { return a - b; }"
}],
"stream": false,
"format": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {"enum": ["bug", "security", "performance"]},
"description": {"type": "string"}
},
"required": ["type", "description"]
}
}
},
"required": ["issues"]
},
"options": {"temperature": 0}
}'
应用应使用同一份 Go 契约发送 Schema 并校验响应。以下程序只依赖标准库,并且只在目标 Endpoint 需要 Bearer Token 时读取 OLLAMA_API_KEY:
package main
import (
"bytes"
"context"
"encoding/json"
"flag"
"fmt"
"io"
"net/http"
"os"
"strings"
"time"
)
const reviewSchema = `{
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {"enum": ["bug", "security", "performance"]},
"description": {"type": "string"}
},
"required": ["type", "description"]
}
}
},
"required": ["issues"]
}`
type Message struct {
Role string `json:"role"`
Content string `json:"content"`
}
type ChatRequest struct {
Model string `json:"model"`
Messages []Message `json:"messages"`
Stream bool `json:"stream"`
Format json.RawMessage `json:"format"`
Options map[string]any `json:"options"`
}
type ChatResponse struct {
Message Message `json:"message"`
}
type Issue struct {
Type string `json:"type"`
Description string `json:"description"`
}
type Review struct {
Issues []Issue `json:"issues"`
}
func requestReview(
ctx context.Context,
client *http.Client,
endpoint string,
model string,
) (ChatResponse, error) {
payload := ChatRequest{
Model: model,
Messages: []Message{{
Role: "user",
Content: "Review: function add(a, b) { return a - b; }",
}},
Stream: false,
Format: json.RawMessage(reviewSchema),
Options: map[string]any{"temperature": 0},
}
body, err := json.Marshal(payload)
if err != nil {
return ChatResponse{}, err
}
request, err := http.NewRequestWithContext(
ctx, http.MethodPost, endpoint, bytes.NewReader(body),
)
if err != nil {
return ChatResponse{}, err
}
request.Header.Set("Content-Type", "application/json")
if key := strings.TrimSpace(os.Getenv("OLLAMA_API_KEY")); key != "" {
request.Header.Set("Authorization", "Bearer "+key)
}
response, err := client.Do(request)
if err != nil {
return ChatResponse{}, err
}
defer response.Body.Close()
if response.StatusCode < 200 || response.StatusCode >= 300 {
message, _ := io.ReadAll(io.LimitReader(response.Body, 4096))
return ChatResponse{}, fmt.Errorf(
"ollama returned %s: %s",
response.Status,
strings.TrimSpace(string(message)),
)
}
var result ChatResponse
if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
return ChatResponse{}, err
}
return result, nil
}
func validateReview(content string) (Review, error) {
var review Review
if err := json.Unmarshal([]byte(content), &review); err != nil {
return Review{}, fmt.Errorf("invalid review JSON: %w", err)
}
if len(review.Issues) > 20 {
return Review{}, fmt.Errorf("too many issues: %d", len(review.Issues))
}
allowed := map[string]bool{
"bug": true, "security": true, "performance": true,
}
for index, issue := range review.Issues {
if !allowed[issue.Type] || strings.TrimSpace(issue.Description) == "" {
return Review{}, fmt.Errorf("invalid issue at index %d", index)
}
}
return review, nil
}
func main() {
endpoint := flag.String("endpoint", "", "Ollama chat endpoint")
model := flag.String("model", "code-reviewer", "model name")
timeout := flag.Duration("timeout", 30*time.Second, "request timeout")
flag.Parse()
response := ChatResponse{
Message: Message{
Content: `{"issues":[{"type":"bug","description":"add subtracts b"}]}`,
},
}
if *endpoint != "" {
ctx, cancel := context.WithTimeout(context.Background(), *timeout)
defer cancel()
var err error
response, err = requestReview(
ctx, &http.Client{Timeout: *timeout}, *endpoint, *model,
)
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
review, err := validateReview(response.Message.Content)
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
output, err := json.MarshalIndent(review, "", " ")
if err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
fmt.Println(string(output))
}
不带参数运行可验证内置离线夹具;传入 -endpoint http://localhost:11434/api/chat 可调用本地服务。直连云端时,传入 -endpoint https://ollama.com/api/chat,通过 -model 选择托管模型,并由 Secret Manager 注入 OLLAMA_API_KEY。解析成功后,还要检查行号范围、执行权限判断,并在高风险动作前要求人工审批。OWASP 将未经校验的模型输出直接交给 Shell、浏览器、SQL、文件路径或高权限函数,归为 Improper Output Handling。
主动选择原生 API 或 OpenAI 兼容接口
Ollama 的 /v1 接口兼容 OpenAI API 中有文档说明的部分能力;它是互操作适配层,而不是无条件的 Drop-in Replacement。需要 Ollama 生命周期控制时优先用 /api,只有当前客户端操作经过契约测试后才使用 /v1。
| 决策维度 | 原生 /api |
OpenAI 兼容 /v1 |
|---|---|---|
| Ollama 特有字段与生命周期 | 直接访问 | 不一定映射全部选项 |
| 复用 OpenAI SDK | 需要 Ollama Client 或 HTTP 层 | 对受支持操作可降低迁移成本 |
| 本地鉴权字段 | 由外围服务控制 | Client 语法上可能要求 API Key,但本地 Ollama 会忽略 |
| 直连云端鉴权 | https://ollama.com/api 使用 Bearer API Key |
https://ollama.com/v1 使用 Bearer API Key |
| 兼容验证 | 固定并测试 Ollama 契约 | 还需测试 Client 版本、参数映射、错误和流式行为 |
不能只改 baseURL 就完成生产迁移。应为实际使用的能力建立契约测试,包括消息角色、流式 Chunk、结构化输出、工具、Usage 字段、取消、超时、重试和错误映射。
实测上下文、模型驻留与请求成本
Ollama 容量取决于模型权重、量化、上下文长度、并发、推理后端和设备分配。上下文越大,内存需求通常越高;模型也可能部分卸载到 CPU,因此不能用通用硬件表代替真实部署测试。
先用 ollama ps 查看当前模型位置与上下文:
ollama ps
API 请求应记录非流式最终响应,或聚合流式响应的最后一个事件。原生响应包含 total_duration、load_duration、prompt_eval_count、prompt_eval_duration、eval_count 和 eval_duration 等字段,耗时单位为纳秒。
curl -s http://localhost:11434/api/generate \
-d '{
"model": "code-reviewer",
"prompt": "解释执行模型生成 Shell 命令的一项风险。",
"stream": false,
"keep_alive": "5m"
}' |
jq '{
total_ms: (.total_duration / 1000000),
load_ms: (.load_duration / 1000000),
prompt_tokens: .prompt_eval_count,
output_tokens: .eval_count,
output_tokens_per_second:
(if .eval_duration > 0
then (.eval_count / (.eval_duration / 1000000000))
else null end)
}'
评测对象应是完整任务,而不是单个热启动请求。需要分开统计冷启动加载、Prompt 评估和 Token 生成,并记录 P50/P95 延迟、失败与超时率、内存压力、处理器位置、输出质量和并发行为。测试必须立即释放模型时可使用 keep_alive: 0;只有测清内存权衡后,才设置有界驻留时长。
Ollama 服务暴露前的安全边界
最稳妥的默认方案是让 Ollama 监听回环地址,并置于应用边界之后。将服务绑定到 localhost 之外,就等于把开发运行时变成可访问的模型服务,必须先补齐网络与应用控制。
| 风险 | 必需控制 | 应保留的证据 |
|---|---|---|
| 未鉴权网络访问 | 回环或私有边界、网关鉴权、TLS、防火墙 | 监听地址、路由策略、访问测试 |
| 跨租户数据暴露 | 应用授权、隔离对话与存储、租户感知日志 | 授权测试与保留策略 |
| 资源耗尽 | 请求体、上下文、并发、超时和模型白名单 | 压测结果与拒绝指标 |
| 危险模型输出 | Schema 校验、上下文编码、参数化查询、工具审批 | 负向测试与阻断日志 |
| 模型来源或许可证风险 | 批准来源、许可证审阅、Checksum 或 Provenance 记录 | 模型清单与审阅责任人 |
| 意外数据传输 | 出站策略,并审阅云模型、遥测、工具、插件和回退 | 网络测试与书面数据流 |
不要把 OLLAMA_ORIGINS="*" 当成通用生产修复。浏览器 Origin 策略不是身份认证,位于局域网也不代表已经获得授权。
Ollama、LM Studio 与 vLLM 如何选
运行时选型取决于运维模型,不存在脱离条件的速度排名。多个运行时都支持同一模型时,应使用相同模型文件和工作负载进行对比。
| 运行时 | 主要优势 | 重要边界 |
|---|---|---|
| Ollama | CLI 优先的本地模型管理、Modelfile、原生 API 与兼容层 | 生产身份、策略、租户和集群控制由外围服务提供 |
| LM Studio | 桌面优先的模型发现、对话与本地实验 | 以 GUI 为中心的流程不同于无头服务与集群运维 |
| vLLM | 面向受支持模型与加速器组合的高吞吐服务能力 | 需要更明确的基础设施、模型、内存和运维规划 |
如果本地工作流简洁性和模型文件控制比共享服务吞吐更重要,Ollama 通常更合适;如果核心要求是批处理、加速器利用率、大并发、弹性伸缩或成熟多租户控制,应评估 vLLM 或其他服务平台。
生产准入与回滚清单
本地 Demo 成功只能证明一个请求在一个环境中运行过。升级为共享服务前,必须同时具备可复现模型、工作负载证据、安全控制和回滚路径。
- 固定并记录 Ollama 版本、模型 Tag、解析后的 Modelfile、模型来源和许可证。
- 使用代表性 Prompt、对抗输入、畸形输出、拒答和领域质量任务进行评测。
- 测试冷启动与热启动延迟、上下文、并发、内存压力、超时、取消和恢复。
- 保持 Ollama 私有,并在外围服务执行身份、租户授权、配额、请求体限制和审计。
- 模型输出和工具参数在渲染、存储、执行或转发前都必须校验。
- 明确数据保留、日志脱敏、出站策略、备份、事件响应和模型下线流程。
- 保留上一版运行时、模型文件、配置和评测结果,以便回滚。
常见问题
Ollama 没有 GPU 也能运行吗?
部分模型和平台组合可以使用 CPU。实际是否可用取决于模型大小与量化、上下文、并发、后端、目标延迟和输出质量。应测试真实任务,并用 ollama ps 检查处理器分配。
Ollama 默认就是私有的吗?
发送到本机回环接口的请求可以在本机推理,但这不能证明端到端隐私。模型下载、云端模型、应用遥测、工具、插件、日志、备份与远程回退都可能形成其他数据路径,必须记录并测试完整链路。
Ollama 能替代 vLLM 吗?
两者能力有重叠,但优化目标不同。Ollama 重视本地开发体验与模型管理,vLLM 重视高吞吐服务。应在相同模型、上下文、并发、硬件和质量条件下比较。
JSON Schema 能让模型输出变安全吗?
不能。Schema 约束响应形状并改善解析,但不能证明事实正确、操作已授权、HTML 或 SQL 安全、文件路径允许,或模型有权调用某个工具。解析后仍要执行常规安全校验。
总结
Ollama 同时降低了本地模型评测与云模型接入门槛,但两条路径都不是完整生产架构。系统必须记录推理位置,保持本地 Daemon 私有,保护直连云端 Key,用 Modelfile 固化配置,校验结构化输出,以真实工作负载决定容量,并保留经过演练的回滚路径。
官方来源
- Ollama API 介绍 — 原生 API 基础地址与请求示例
- Ollama API 鉴权 — 本地无鉴权边界与直连云端 Bearer 鉴权
- Ollama Cloud — 直连云端、模型命名、数据处理与仅本地控制
- Ollama Modelfile 参考 — 支持的指令与参数
- Ollama 结构化输出 — JSON 模式、JSON Schema、Pydantic 与 Zod 校验示例
- Ollama 上下文长度 — 上下文配置、内存权衡与
ollama ps - Ollama OpenAI 兼容说明 — 已文档化的兼容范围与示例
- Ollama Anthropic 兼容说明 — 本地与托管
/v1/messages行为 - Ollama FAQ — 本地访问、网络、云端模型与运行配置
- OWASP LLM05:Improper Output Handling — 模型输出校验与上下文安全处理
延伸阅读
- Ollama — Ollama 术语定义与核心概念速查
- 本地大模型部署实战:Ollama vs vLLM 性能调优与选型决策 — 生产环境下 Ollama 与 vLLM 的对比基准测试
- LLM 推理 KV Cache 详解 — 理解上下文长度、并发和缓存精度如何影响推理内存
- 小语言模型边缘部署实战 — 在边缘设备上用 Ollama 部署轻量模型
- 模型量化技术详解 — 理解 GGUF、GPTQ 等量化格式在 Ollama 中的应用