Ollama Provider¶
1. 定位¶
Ollama 是本地模型 Provider,让用户在自己的机器上运行大模型.优势: - 完全隐私(数据不离开本地) - 无 API 成本 - 支持众多开源模型(Llama, Mistral, CodeLlama 等)
2. 支持的模型¶
Ollama 动态获取模型列表,从 /api/tags 端点实时拉取.
常见模型:
| 模型 | Context | 备注 |
|---|---|---|
| llama3.3 | 128K | Meta 最新 |
| mistral | 8K | 小而快 |
| codellama | 16K | 代码专用 |
| mixtral | 32K | MoE 模型 |
| qwen2.5 | 32K | 阿里开源 |
注意: 首次使用需要先拉取模型:
3. 配置示例¶
import "git.flytoex.net/yuanwei/git.flytoex.net/yuanwei/flyto-agent/pkg/providers/ollama"
p := ollama.New(ollama.Config{
BaseURL: "http://localhost:11434", // 默认
Timeout: 5 * time.Minute, // 可选, 默认 300s, 见 §3.1
})
3.1 Timeout (P1 契约加固, 2026-04-13)¶
Config.Timeout 通过 http.Transport.ResponseHeaderTimeout 实现, 约束"请求发出到收到响应首字节"的时间, 不影响 SSE 流式 body 读取.
Ollama 默认 300s (5 分钟), 比云端 provider 长 5 倍:
| Provider 类型 | 默认 Timeout | 理由 |
|---|---|---|
| 云端 (anthropic/openai/gemini/...) | 60s | 商业 LLM 通常 < 10s 开始响应 |
| 本地 (ollama/lmstudio) | 300s | 本地模型冷启动需 load 权重到 GPU,llama 70B 类大模型可能耗时 1-2 分钟 |
冷启动 vs 温启动: - 冷启动: 第一次调用某个模型, ollama 需要从磁盘 load 权重 + warm-up KV cache, 30-90s 是常态 - 温启动: 模型已 load 在显存中, 通常 < 5s 开始响应
如果你只跑小模型 (7B/13B) 或者一直保持模型常驻, 可以把 Timeout 调到 60-90s 让超时更敏感; 如果跑 70B+ 大模型频繁切换, 用默认 300s.
| 场景 | Config 字段 | 行为 |
|---|---|---|
| 默认 | HTTPClient=nil, Timeout=0 |
使用 defaultTimeout=300s |
| 显式 Timeout | HTTPClient=nil, Timeout=Xs |
使用 Xs |
| 自定义 client | HTTPClient=&http.Client{...} |
完全交给消费者, Timeout 被忽略 |
陷阱警告: 不要误用 http.Client.Timeout - 详见 anthropic.md §3.1.
自定义 Model¶
Ollama 支持自定义模型(Modelfile),只要在 /api/tags 中返回即可.
4. 认证方式¶
无认证 - Ollama 默认不需要 API Key.
实现会发送空的 Bearer token,但 Ollama 会忽略.
5. 能力矩阵¶
| 能力 | 支持 | 备注 |
|---|---|---|
| Streaming | ✓ | SSE |
| Tool Use | ✓ | 取决于模型 |
| Extended Thinking | ✗ | 不支持 |
| Vision | ✓(部分) | 如 llava |
| JSON Mode | ✓ | 取决于模型 |
| Caching | ✗ | 不支持 |
| Batch API | ✗ | 不支持 |
| 并发 Tool Call | ✓ | 取决于模型 |
6. 已知 quirks¶
动态模型获取¶
Ollama 没有静态模型表.New() 只构造 client,不发请求,Provider 初始化总是成功;只有调用 Models(ctx) 时才会访问 /api/tags,此时 Ollama 服务必须可达,否则返回 ollama: fetch models: ... 错误.Stream() 直接走 /v1/chat/completions 兼容端点,无需先列模型.
Schema Adaptation¶
使用 "openai" schema adaptation(非 strict),因为本地模型对格式要求更宽松.
Tool 限制¶
Tool 数量无硬限制(MaxTools = 0).
无 Thinking¶
Ollama 模型不支持 Extended Thinking.
推荐超时配置¶
p := ollama.New(ollama.Config{
HTTPClient: &http.Client{
Timeout: 5 * time.Minute, // 本地推理可能很慢
},
})
7. 错误处理¶
| 错误 | 含义 | 处理建议 |
|---|---|---|
| connection refused | Ollama 未启动 | ollama serve |
| 404 | 模型未拉取 | ollama pull <model> |
| 500 | 模型推理错误 | 检查模型文件 |
8. 与 LM Studio 对比¶
| 特性 | Ollama | LM Studio |
|---|---|---|
| 模型管理 | CLI | GUI |
| API 风格 | OpenAI 兼容 | OpenAI 兼容 |
| 模型格式 | .gguf, Modelfile | .gguf |
| 工具支持 | 取决于模型 | 取决于模型 |
| 热加载 | 支持 | 支持 |
| 团队共享 | 难(各自部署) | 难(各自部署) |
9. 使用场景¶
最佳场景: - 隐私敏感:代码不离开本地 - 离线开发:无网络环境 - 成本控制:无 API 费用 - 开发测试:免费试用各种模型
10. 数据驱动能力(Capabilities)¶
参见
docs/architecture/data-driven-capabilities-rfc.md了解整体机制.PR2.1(2026-04)落地,是整个 PR2 的模板锚点.
本 provider 的能力决策来自 req.Capabilities(engine 从 ModelRegistry 注入).包内 const ollamaMaxTools = 0 降级为兜底.
本 provider 的决策路径:
| 路径 | helper | 兜底策略 |
|---|---|---|
MaxTools + Exhaustive |
resolveMaxTools |
ollamaMaxTools = 0(本地模型无硬限制) |
SupportsThinking |
resolveThinkingSupport |
兜底 false(包注释声明本地模型不支持结构化 thinking) |
SupportsCaching |
不使用 | ollama 不支持 caching,无 Config 字段 |
ollama 已知债务(LEGACY):ollama Stream() 当前完全不转发 req.NeedsThinking 到 wire 层.即使 registry 说模型 SupportsThinking=true(未来 DeepSeek-R1 等推理模型)且用户 NeedsThinking=true,ollama 仍会 silent disable thinking.PR2.1 不在范围内修复此债务--PR2 是"推广数据驱动抽象"而非"加新功能".当前 detectFeatureWarnings 严格遵循 want×can 协议,不对这种"模型支持但 provider 不转发"的情况发明新语义;待 ollama 加 thinking 支持时再一并消除.
双开关协议(want × can):req.NeedsThinking=true 是 want 信号;registry 或兜底 false 是 can 信号.want=true can=false → warning.对于兜底 false 路径(大多数本地模型),nil Capabilities + NeedsThinking=true 就会发 warning,提示用户当前模型不支持 thinking.