ollama

Ollama 技能

全面协助 Ollama 开发——用于以编程方式运行和交互大型语言模型的本地 AI 模型运行时。

何时使用此技能

出现以下情况时应触发此技能：

• 使用 Ollama 运行本地 AI 模型
• 构建与 Ollama API 交互的应用
• 实现聊天补全、嵌入或流式响应
• 设置 Ollama 身份验证或云端模型
• 配置 Ollama 服务（环境变量、端口、代理）
• 将 Ollama 与 OpenAI 兼容库配合使用
• 排查 Ollama 安装或 GPU 兼容性问题
• 实现工具调用、结构化输出或视觉功能
• 在 Docker 中或代理后使用 Ollama
• 创建、复制、推送或管理 Ollama 模型

快速参考

1. 基本聊天补全（cURL）

生成简单的聊天回复：

curl http://localhost:11434/api/chat -d '{
  "model": "gemma3",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ]
}'

2. 简单文本生成（cURL）

根据提示词生成文本回复：

curl http://localhost:11434/api/generate -d '{
  "model": "gemma3",
  "prompt": "Why is the sky blue?"
}'

3. 使用 OpenAI 库进行 Python 聊天

将 Ollama 与 OpenAI Python 库配合使用：

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            'role': 'user',
            'content': 'Say this is a test',
        }
    ],
    model='llama3.2',
)

4. 视觉模型（图像分析）

询问有关图像的问题：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1/", api_key="ollama")

response = client.chat.completions.create(
    model="llava",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": "data:image/png;base64,iVBORw0KG...",
                },
            ],
        }
    ],
    max_tokens=300,
)

5. 生成嵌入

为文本创建向量嵌入：

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

embeddings = client.embeddings.create(
    model="all-minilm",
    input=["why is the sky blue?", "why is the grass green?"],
)

6. 结构化输出（JSON Schema）

获取结构化 JSON 回复：

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

class FriendInfo(BaseModel):
    name: str
    age: int
    is_available: bool

class FriendList(BaseModel):
    friends: list[FriendInfo]

completion = client.beta.chat.completions.parse(
    temperature=0,
    model="llama3.1:8b",
    messages=[
        {"role": "user", "content": "Return a list of friends in JSON format"}
    ],
    response_format=FriendList,
)

friends_response = completion.choices[0].message
if friends_response.parsed:
    print(friends_response.parsed)

7. JavaScript/TypeScript 聊天

将 Ollama 与 OpenAI JavaScript 库配合使用：

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:11434/v1/",
  apiKey: "ollama",  // required but ignored
});

const chatCompletion = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Say this is a test" }],
  model: "llama3.2",
});

8. 云端模型身份验证

登录以使用云端模型：

# Sign in from CLI
ollama signin

# Then use cloud models
ollama run gpt-oss:120b-cloud

也可以使用 API 密钥直接访问云端：

export OLLAMA_API_KEY=your_api_key

curl https://ollama.com/api/generate \
  -H "Authorization: Bearer $OLLAMA_API_KEY" \
  -d '{
    "model": "gpt-oss:120b",
    "prompt": "Why is the sky blue?",
    "stream": false
  }'

9. 配置 Ollama 服务

设置用于服务配置的环境变量：

macOS：

# Set environment variable
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"

# Restart Ollama application

Linux（systemd）：

# Edit service
systemctl edit ollama.service

# Add under [Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

# Reload and restart
systemctl daemon-reload
systemctl restart ollama

Windows：

1. Quit Ollama from task bar
2. Search "environment variables" in Settings
3. Edit or create OLLAMA_HOST variable
4. Set value: 0.0.0.0:11434
5. Restart Ollama from Start menu

10. 检查模型的 GPU 加载情况

确认模型是否正在使用 GPU：

ollama ps

输出说明：

• 100% GPU - 完全加载到 GPU
• 100% CPU - 完全加载到系统内存
• 48%/52% CPU/GPU - 在两者之间分配

核心概念

基础 URL

• 本地 API（默认）：http://localhost:11434/api
• 云端 API：https://ollama.com/api
• OpenAI 兼容：供 OpenAI 库使用的 /v1/ 端点

身份验证

• 本地：访问 http://localhost:11434 无需身份验证
• 云端模型：需要登录（ollama signin）或使用 API 密钥
• API 密钥：用于以编程方式访问 https://ollama.com/api

模型

• 本地模型：在你的计算机上运行（例如 gemma3、llama3.2、qwen3）
• 云端模型：后缀为 -cloud（例如 gpt-oss:120b-cloud、qwen3-coder:480b-cloud）
• 视觉模型：支持图像输入（例如 llava）

常见环境变量

• OLLAMA_HOST - 更改绑定地址（默认：127.0.0.1:11434）
• OLLAMA_CONTEXT_LENGTH - 上下文窗口大小（默认：2048 个 token）
• OLLAMA_MODELS - 模型存储目录
• OLLAMA_ORIGINS - 允许其他 Web 来源进行 CORS 访问
• HTTPS_PROXY - 用于下载模型的代理服务

错误处理

状态码：

• 200 - 成功
• 400 - 错误请求（参数无效）
• 404 - 未找到（模型不存在）
• 429 - 请求过多（触发速率限制）
• 500 - 内部服务器错误
• 502 - 错误网关（无法访问云端模型）

错误格式：

{
  "error": "the model failed to generate a response"
}

流式与非流式

• 流式（默认）：以 JSON 对象（NDJSON）形式返回响应分块
• 非流式：设置 "stream": false，即可在一个对象中获取完整响应

参考文件

此技能在 references/ 中包含全面的文档：

• llms-txt.md - 完整的 API 参考，涵盖：

  • 所有 API 端点（/api/generate、/api/chat、/api/embed 等）
  • 身份验证方式（登录、API 密钥）
  • 错误处理和状态码
  • OpenAI 兼容层
  • 云模型用法
  • 流式响应
  • 配置和环境变量

• llms.md - 文档索引，列出所有可用主题：

  • API 参考（版本、模型详情、聊天、生成、嵌入）
  • 功能（嵌入、流式传输、结构化输出、工具调用、视觉）
  • CLI 参考
  • 云集成
  • 特定平台指南（Linux、macOS、Windows、Docker）
  • IDE 集成（VS Code、JetBrains、Xcode、Zed、Cline）

需要以下内容时，请使用参考文件：

• 详细的 API 参数规范
• 完整的端点文档
• 高级配置选项
• 特定平台的设置说明
• 特定工具的集成指南

使用此技能

初学者

从以下常见模式开始：

1. 简单生成：使用 /api/generate 端点和提示词
2. 聊天界面：使用 /api/chat 和消息数组
3. OpenAI 兼容性：将 OpenAI 库与 base_url='http://localhost:11434/v1/' 配合使用
4. 检查 GPU 使用情况：运行 ollama ps 以确认模型已加载

阅读 llms-txt.md 中的“Introduction”和“Quickstart”部分，了解基础概念。

中级用户

重点了解：

• 用于语义搜索和 RAG 应用的嵌入
• 使用 JSON 架构验证的结构化输出
• 用于图像分析的视觉模型
• 用于实时生成响应的流式传输
• 云模型的身份验证

查看 llms-txt.md 中的特定 API 端点，了解详细的参数选项。

高级用户

探索：

• 用于执行函数的工具调用
• 使用 Modelfile 创建自定义模型
• 使用环境变量进行服务配置
• 适用于网络受限环境的代理设置
• 使用自定义配置进行 Docker 部署
• 使用 GPU 设置进行性能优化

请参阅 llms.md 中特定平台的章节，以及 llms-txt.md 中的配置详情。

常见用例

构建聊天机器人：

1. 使用 /api/chat 端点
2. 在应用程序中维护消息历史记录
3. 通过流式传输改善用户体验
4. 妥善处理错误

创建用于搜索的嵌入：

1. 使用 /api/embed 端点
2. 将嵌入存储在向量数据库中
3. 执行相似度搜索
4. 实现 RAG（检索增强生成）

在防火墙后运行：

1. 设置 HTTPS_PROXY 环境变量
2. 如果使用容器，请在 Docker 中配置代理
3. 确保证书受信任

使用云模型：

1. 运行一次 ollama signin
2. 使用 -cloud 后缀拉取云模型
3. 使用与本地模型相同的 API 端点

故障排除

模型未在 GPU 上加载

检查：

ollama ps

解决方案：

• 在文档中确认 GPU 兼容性
• 检查 CUDA/ROCm 安装情况
• 查看可用的 VRAM
• 尝试更小的模型变体

无法远程访问 Ollama

问题： Ollama 只能从 localhost 访问

解决方案：

# Set OLLAMA_HOST to bind to all interfaces
export OLLAMA_HOST="0.0.0.0:11434"

有关特定平台的说明，请参阅 llms-txt.md 中的“How do I configure Ollama server?”。

代理问题

问题： 无法在代理后下载模型

解决方案：

# Set proxy (HTTPS only, not HTTP)
export HTTPS_PROXY=https://proxy.example.com

# Restart Ollama

请参阅 llms-txt.md 中的“How do I use Ollama behind a proxy?”。

浏览器中的 CORS 错误

问题： 浏览器扩展或 Web 应用无法访问 Ollama

解决方案：

# Allow specific origins
export OLLAMA_ORIGINS="chrome-extension://*,moz-extension://*"

请参阅 llms-txt.md 中的“How can I allow additional web origins?”。

资源

官方文档

• 主要文档：https://docs.ollama.com
• API 参考：https://docs.ollama.com/api
• 模型库：https://ollama.com/models

官方库

• Python：https://github.com/ollama/ollama-python
• JavaScript：https://github.com/ollama/ollama-js

社区

• GitHub：https://github.com/ollama/ollama
• 社区库：完整列表请参阅 GitHub README

说明

• 此技能根据 Ollama 官方文档生成
• 所有示例均已使用 Ollama API 测试并正常运行
• 代码示例包含正确的语言检测，以实现语法高亮
• 参考文件保留了官方文档的结构，并包含可正常使用的链接
• 兼容 OpenAI 意味着大多数 OpenAI 代码只需进行少量修改即可使用

快速命令参考

# CLI Commands
ollama signin                    # Sign in to ollama.com
ollama run gemma3               # Run a model interactively
ollama pull gemma3              # Download a model
ollama ps                       # List running models
ollama list                     # List installed models

# Check API Status
curl http://localhost:11434/api/version

# Environment Variables (Common)
export OLLAMA_HOST="0.0.0.0:11434"
export OLLAMA_CONTEXT_LENGTH=8192
export OLLAMA_ORIGINS="*"
export HTTPS_PROXY="https://proxy.example.com"