ollama

Ollama

概述

此技能可帮助用户将 Ollama 集成到项目中，以便在本地运行大模型。此技能会指导用户完成设置、连接验证、模型管理，以及 Python 和 Node.js 应用的 API 集成。Ollama 提供简单的 API，可在本地运行 Llama、Mistral、Gemma 等模型，无需依赖云服务。

何时使用此技能

在用户希望进行以下操作时使用此技能：

• 在自己的设备上本地运行大模型
• 构建无需依赖云服务的 AI 应用
• 实现文本生成、聊天或嵌入功能
• 实时流式传输 LLM 响应
• 创建 RAG（检索增强生成）系统
• 将本地 AI 功能集成到 Python 或 Node.js 项目中
• 管理 Ollama 模型（拉取、列出、删除）
• 验证 Ollama 连接并排查连接问题

安装和设置

步骤 1：收集 Ollama URL

重要提示：务必询问用户的 Ollama URL。不要假设 Ollama 在本地运行。

询问用户：“你的 Ollama 服务 URL 是什么？”

常见场景：

• 本地安装：http://localhost:11434（默认）
• 远程服务：http://192.168.1.100:11434
• 自定义端口：http://localhost:8080
• Docker：http://localhost:11434（如果端口映射到 11434）

如果用户表示 Ollama 在本地运行，或不知道 URL，建议尝试 http://localhost:11434。

步骤 2：检查是否已安装 Ollama

继续操作前，请验证 Ollama 是否已安装，并在提供的 URL 上运行。用户可以在浏览器中访问该 URL，或运行以下命令进行检查：

curl <OLLAMA_URL>/api/version

如果尚未安装 Ollama，请指导用户安装：

macOS/Linux：

curl -fsSL https://ollama.com/install.sh | sh

Windows： 从 https://ollama.com/download 下载

Docker：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

步骤 3：启动 Ollama 服务

确保 Ollama 正在运行：

macOS/Linux：

ollama serve

Docker：

docker start ollama

该服务通常默认运行在 http://localhost:11434。

步骤 4：验证连接

使用验证脚本测试连接，并列出可用模型。

重要提示：脚本路径是相对于技能目录的。运行脚本时，请选择以下任一方式：

1. 使用技能目录的完整路径（例如，/path/to/ollama/scripts/validate_connection.py）
2. 先切换到技能目录，再运行 python scripts/validate_connection.py

# Run from the skill directory
cd /path/to/ollama
python scripts/validate_connection.py <OLLAMA_URL>

使用用户的 Ollama URL 的示例：

cd /path/to/ollama
python scripts/validate_connection.py http://192.168.1.100:11434

该脚本将：

• 规范化 URL（移除所有路径部分）
• 检查是否可以访问 Ollama
• 显示 Ollama 版本
• 列出所有已安装模型及其大小
• 如果连接失败，则提供故障排除指南

成功输出：

✓ Connection successful!
  URL: http://localhost:11434
  Version: Ollama 0.1.0
  Models available: 2

Installed models:
  - llama3.2 (4.7 GB)
  - mistral (7.2 GB)

失败输出：

✗ Connection failed: Connection refused
  URL: http://localhost:11434

Troubleshooting:
  1. Ensure Ollama is installed and running
  2. Check that the URL is correct
  3. Verify Ollama is accessible at the specified URL
  4. Try: curl http://localhost:11434/api/version

模型管理

拉取模型

帮助用户从 Ollama 库下载模型。常见模型包括：

• llama3.2 - Meta 的 Llama 3.2（不同大小：1B、3B）
• llama3.1 - Meta 的 Llama 3.1（8B、70B、405B）
• mistral - Mistral 7B
• phi3 - Microsoft Phi-3
• gemma2 - Google Gemma 2

用户可以通过以下方式拉取模型：

ollama pull llama3.2

也可以使用 API 以编程方式拉取（示例见参考文档）。

列出模型

指导用户列出已安装的模型：

ollama list

也可以使用验证脚本查看模型的详细信息。

删除模型

帮助用户删除模型以释放空间：

ollama rm llama3.2

模型选择指南

根据用户的需求，帮助他们选择合适的模型：

• 小型模型（1-3B）：速度快，适合简单任务，所需资源较少
• 中型模型（7-13B）：性能与质量均衡
• 大型模型（70B+）：质量最佳，需要大量资源

实现指南

Python 项目

对于基于 Python 的项目，请参考 Python API 参考文档：

• 文件：references/python_api.md
• 用法：实现 Python 集成时加载此参考文档
• 包含内容：
  • 使用 urllib.request（标准库）的 REST API 示例
  • 使用 Generate API 生成文本
  • 使用 Chat API 构建对话界面
  • 用于实时输出的流式响应（推荐）
  • 用于语义搜索的嵌入
  • 完整的 RAG 系统示例
  • 错误处理模式
  • 用于声明依赖项的 PEP 723 内联脚本元数据
• 无需依赖项：仅使用 Python 标准库

重要：为用户创建 Python 脚本时，请添加 PEP 723 内联脚本元数据以声明依赖项。示例请参阅参考文档。

默认使用流式传输：实现文本生成或聊天时，除非用户明确要求非流式响应，否则请使用流式响应。

常见 Python 用例：

# Streaming text generation (RECOMMENDED)
for token in generate_stream("Explain quantum computing"):
    print(token, end="", flush=True)

# Streaming chat conversation (RECOMMENDED)
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]
for token in chat_stream(messages):
    print(token, end="", flush=True)

# Non-streaming (use only when needed)
response = generate("Explain quantum computing")

# Embeddings for semantic search
embedding = get_embeddings("Hello, world!")

Node.js 项目

对于基于 Node.js 的项目，请参考 Node.js API 参考文档：

• 文件：references/nodejs_api.md
• 用法：实现 Node.js 集成时加载此参考文档
• 包含内容：
  • 官方 ollama npm 包示例
  • 替代方案 Fetch API 示例（Node.js 18+）
  • 文本生成和聊天 API
  • 使用异步迭代器进行流式传输（推荐）
  • 嵌入和语义相似度
  • 完整的 RAG 系统示例
  • 错误处理和重试逻辑
  • TypeScript 支持示例

安装：

npm install ollama

默认使用流式传输：实现文本生成或聊天时，除非用户明确要求非流式响应，否则请使用流式响应。

常见 Node.js 用例：

import { Ollama } from 'ollama';
const ollama = new Ollama();

// Streaming text generation (RECOMMENDED)
const stream = await ollama.generate({
  model: 'llama3.2',
  prompt: 'Explain quantum computing',
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.response);
}

// Streaming chat conversation (RECOMMENDED)
const chatStream = await ollama.chat({
  model: 'llama3.2',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ],
  stream: true
});

for await (const chunk of chatStream) {
  process.stdout.write(chunk.message.content);
}

// Non-streaming (use only when needed)
const response = await ollama.generate({
  model: 'llama3.2',
  prompt: 'Explain quantum computing'
});

// Embeddings
const embedding = await ollama.embeddings({
  model: 'llama3.2',
  prompt: 'Hello, world!'
});

常见集成模式

文本生成

根据提示词生成文本补全。用例：

• 内容生成
• 代码补全
• 问答
• 摘要生成

引导用户根据其用例，使用带有适当参数（temperature、top_p 等）的 Generate API。

对话界面

使用对话历史构建聊天应用。用例：

• 聊天机器人
• 虚拟助手
• 客户支持
• 交互式教程

引导用户使用 Chat API 管理消息历史。说明系统提示词对于控制行为的重要性。

嵌入与语义搜索

生成文本的向量嵌入。用例：

• 语义搜索
• 文档相似度
• RAG 系统
• 推荐系统

引导用户使用 Embeddings API，并通过余弦相似度比较嵌入。

流式响应

推荐做法：始终优先使用流式传输，以提供更好的用户体验。

逐个词元流式输出 LLM 的内容。用例：

• 实时聊天界面
• 渐进式内容生成
• 改善长篇输出的用户体验
• 为用户提供即时反馈

为用户编写代码时，默认使用流式 API，除非他们明确要求非流式响应。

引导用户：

• 在 API 调用中启用 stream: true
• 处理异步迭代（Node.js）或生成器（Python）
• 在词元到达时显示，以提供实时反馈
• 在生成期间显示进度指示器

RAG（检索增强生成）

结合文档检索与生成。用例：

• 针对文档进行问答
• 知识库聊天机器人
• 感知上下文的辅助

引导用户：

1. 为文档生成嵌入
2. 存储嵌入及其关联文本
3. 使用查询嵌入搜索相关文档
4. 将检索到的上下文注入提示词
5. 使用上下文生成答案

两份参考文档都包含完整的 RAG 系统示例。

最佳实践

安全

• 切勿将敏感信息硬编码
• 使用环境变量进行配置
• 发送给 LLM 前验证并清理用户输入

性能

• 对于较长的响应，使用流式传输以提升感知性能
• 为不会变化的文档缓存嵌入
• 根据使用场景选择合适大小的模型
• 选择模型时考虑响应时间要求

错误处理

• 始终为网络故障实现适当的错误处理
• 发出请求前检查模型是否可用
• 向用户提供有帮助的错误消息
• 为暂时性故障实现重试逻辑

连接管理

• 在继续实现前验证连接
• 妥善处理连接超时
• 对于远程 Ollama 实例，确保网络可访问
• 在开发期间使用验证脚本

模型管理

• 拉取大型模型前检查可用磁盘空间
• 仅保留正在使用的模型
• 告知用户模型的下载大小
• 根据需求提供模型选择建议

上下文管理

• 对于聊天应用，管理对话历史以避免达到令牌限制
• 对话过长时，删减较早的消息
• 对于较长的对话历史，考虑使用摘要

故障排除

连接问题

如果连接失败：

1. 验证 Ollama 是否已安装：ollama --version
2. 检查 Ollama 是否正在运行：curl http://localhost:11434/api/version
3. 重启 Ollama 服务：ollama serve
4. 检查远程连接的防火墙设置
5. 验证 URL 格式（应为 http://host:port，且不包含路径）

未找到模型

如果模型不可用：

1. 列出已安装的模型：ollama list
2. 拉取所需模型：ollama pull model-name
3. 验证模型名称的拼写（区分大小写）

内存不足

如果内存不足：

1. 使用较小的模型变体
2. 关闭其他应用程序
3. 增加系统交换空间
4. 考虑使用 RAM 更多的机器

性能缓慢

如果响应缓慢：

1. 使用较小的模型
2. 减小 num_predict 参数
3. 检查 CPU/GPU 使用情况
4. 如果可用，确保 Ollama 正在使用 GPU
5. 关闭其他占用大量资源的应用程序

资源

scripts/validate_connection.py

用于验证 Ollama 连接并列出可用模型的 Python 脚本。该脚本会规范化 URL、测试连接、显示版本信息，并提供故障排除建议。

references/python_api.md

全面的 Python API 参考，包含以下示例：

• 安装和设置
• 连接验证
• 模型管理（列出、拉取、删除）
• 用于文本补全的 Generate API
• 用于对话的 Chat API
• 流式响应
• 嵌入和语义搜索
• 完整的 RAG 系统实现
• 错误处理模式
• 最佳实践

references/nodejs_api.md

全面的 Node.js API 参考，包含以下示例：

• 使用 npm 安装
• 官方 ollama 包的用法
• 替代的 Fetch API 示例
• 模型管理
• Generate 和 Chat API
• 使用异步迭代器进行流式传输
• 嵌入和语义相似度
• 完整的 RAG 系统实现
• 错误处理和重试逻辑
• TypeScript 支持
• 最佳实践