Ollama

一、Ollama 简介

Ollama 是一个轻量级的本地大语言模型运行工具，支持一键拉取和运行主流开源模型（Llama、Qwen、DeepSeek 等），并提供 REST API 服务，兼容 OpenAI 和 Anthropic 接口协议。

二、常用命令

模型管理

| 命令 | 说明 |
| ------ |------ |
| ollama serve | 启动 API 服务（默认后台已运行） |
| ollama run | 下载并运行模型，进入交互聊天 |
| ollama pull | 下载模型（不进入交互） |
| ollama push | 推送模型到仓库 |
| ollama rm | 删除已下载模型 |
| ollama cp | 复制/重命名模型 |
| ollama create -f | 从 Modelfile 创建自定义模型 |
| ollama show | 查看模型详细信息 |
| ollama list | 查看已下载的模型 |
| ollama ps | 查看当前正在运行的模型 |

常用模型推荐

ollama pull qwen2.5:7b           # 中文能力强
ollama pull llama3.1:8b          # 通用
ollama pull gemma2:9b            # Google 出品
ollama pull mistral:7b           # 轻量高效
ollama pull deepseek-r1:7b       # 推理模型
ollama pull codellama:7b         # 代码专用

三、API 服务配置

Ollama 默认在 http://localhost:11434 启动 REST API 服务。

远程访问

默认只监听 localhost，如需从其他机器访问：

# Linux/Mac
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# Windows - 设置系统环境变量
# OLLAMA_HOST=0.0.0.0:11434

⚠️ 远程暴露时无任何认证，建议配合反向代理加鉴权。

自定义 Modelfile

FROM qwen2.5:7b
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 4096
SYSTEM 你是一个专业的中文助手，回答简洁准确。

创建自定义模型：

ollama create my-qwen -f Modelfile

四、OpenAI 兼容接口

Ollama 提供 OpenAI 兼容的 /v1 端点，可直接对接任何支持 OpenAI SDK 的工具。

连接配置

• Base URL: http://localhost:11434/v1
• API Key: ollama（任意值，不校验）

Chat 调用（Python）

from openai import OpenAI

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

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

Chat 调用（cURL）

curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "你好"}]
}'

Embedding 调用

response = client.embeddings.create(
    model="nomic-embed-text",
    input="这是一段需要向量化的文本"
)
print(len(response.data[0].embedding))  # 768

五、Anthropic 兼容接口

Ollama 同时支持 Anthropic Messages API 协议，可对接 Claude 生态的工具。

连接配置

• Base URL: http://localhost:11434/v1
• API Key: ollama（任意值）

Anthropic SDK 调用（Python）

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

message = client.messages.create(
    model="qwen2.5:7b",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "你好，介绍一下你自己"}
    ]
)
print(message.content[0].text)

流式调用

with client.messages.stream(
    model="qwen2.5:7b",
    max_tokens=1024,
    messages=[{"role": "user", "content": "讲个故事"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Anthropic 原生 API 格式（cURL）

curl http://localhost:11434/v1/messages -d '{
  "model": "qwen2.5:7b",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}'

系统提示词

message = client.messages.create(
    model="qwen2.5:7b",
    max_tokens=1024,
    system="你是一个专业的翻译助手，请将用户输入翻译成英文。",
    messages=[
        {"role": "user", "content": "今天天气真好"}
    ]
)
print(message.content[0].text)

多轮对话

messages = [
    {"role": "user", "content": "什么是机器学习？"},
    {"role": "assistant", "content": "机器学习是人工智能的一个分支..."},
    {"role": "user", "content": "能举个例子吗？"}
]

message = client.messages.create(
    model="qwen2.5:7b",
    max_tokens=1024,
    messages=messages
)
print(message.content[0].text)

六、Ollama 原生 API

除兼容接口外，Ollama 也提供自己的原生 API。

聊天

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "你好"}]
}'

文本生成

curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "你好"
}'

向量生成

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "这是一段需要向量化的文本"
}'

批量向量化

curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": ["第一段文本", "第二段文本", "第三段文本"]
}'

模型列表

curl http://localhost:11434/api/tags

七、向量模型（Embedding）

常用向量模型

ollama pull nomic-embed-text        # 768维，轻量高效，社区最常用
ollama pull mxbai-embed-large       # 1024维，英文
ollama pull bge-m3                  # 1024维，多语言（中文友好）
ollama pull snowflake-arctic-embed  # 1024维
ollama pull all-minilm              # 384维，超轻量

模型选择建议

| 场景 | 推荐模型 | 维度 | 说明 |
| ------ |------ |------ |------ |
| 中文为主 | bge-m3 | 1024 | 多语言，中文效果好 |
| 英文为主 | nomic-embed-text | 768 | 轻量，社区最常用 |
| 超轻量/快速 | all-minilm | 384 | 资源极少，精度略低 |
| 高精度英文 | mxbai-embed-large | 1024 | 精度更高，占用更多 |

⚠️ 写入和查询必须用同一个向量模型，否则维度或语义空间不匹配会导致检索结果很差。

与向量数据库配合

常见搭配：Ollama（生成向量） + ChromaDB / Milvus / Qdrant（存储和检索）

import chromadb
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
chroma = chromadb.Client()
collection = chroma.create_collection("docs")

# 写入
docs = ["文档内容1", "文档内容2"]
embeddings = client.embeddings.create(model="nomic-embed-text", input=docs)
collection.add(
    ids=["id1", "id2"],
    documents=docs,
    embeddings=[e.embedding for e in embeddings.data]
)

# 查询
query_emb = client.embeddings.create(
    model="nomic-embed-text", input="搜索关键词"
).data[0].embedding
results = collection.query(query_embeddings=[query_emb], n_results=3)
print(results["documents"])

八、接口协议对照

| 特性 | OpenAI 兼容 | Anthropic 兼容 | Ollama 原生 |
| ------ |------ |------ |------ |
| 端点 | /v1/chat/completions | /v1/messages | /api/chat |
| 认证 | 不需要 | 不需要 | 不需要 |
| 流式 | stream: true | stream: true | stream: true |
| Embedding | /v1/embeddings | — | /api/embed |
| SDK | openai | anthropic | requests / httpx |
| 适用工具 | ChatGPT-Next-Web, LobeChat 等 | Claude 生态工具 | 自定义开发 |

快速配置速查

OpenAI 兼容:

• Base URL: http://localhost:11434/v1
• API Key: ollama

Anthropic 兼容:

• Base URL: http://localhost:11434/v1
• API Key: ollama

Ollama 原生:

• Endpoint: http://localhost:11434/api/*
• 认证: 无

以上就是 Ollama 本地部署的完整使用指南，涵盖命令行操作、三种 API 协议对接方式以及向量模型的使用。