Ollama作为目前最流行的本地大模型运行工具之一，很多人只知道用ollama run命令在终端里对话，却忽略了它内置的HTTP服务能力。实际上，只要Ollama启动，它就默认在11434端口监听一个REST API，所有功能都可以通过HTTP请求调用。更方便的是，Ollama还提供了与OpenAI完全兼容的接口端点，让现有代码几乎零成本迁移到本地模型上。
一、Ollama原生API的两个核心接口
Ollama原生API的基础地址是http://localhost:11434，最常用的有两个接口：/api/generate用于单轮文本生成，/api/chat用于多轮对话。两者的区别在于传参方式：generate接收一个prompt字符串，chat则接收一个messages数组，每条消息包含role和content两个字段。
先看generate接口的最简调用，用curl就能测试：
curl http://localhost:11434/api/generate -d '{
"model": "llama3",
"prompt": "为什么天空是蓝色的？",
"stream": false
}'注意stream参数默认为true，也就是默认按流式返回，每行一个JSON对象。如果想要一次性拿到完整结果，必须显式设置为false。非流式响应会返回一个包含response字段的JSON，同时还有eval_count、eval_duration等字段可以用来计算token生成速度。
chat接口更适合构建对话应用，消息历史直接放在messages数组里：
import requests
url = "http://localhost:11434/api/chat"
payload = {
"model": "llama3",
"messages": [
{"role": "system", "content": "你是一个简洁的中文助手"},
{"role": "user", "content": "介绍一下你自己"}
],
"stream": False
}
resp = requests.post(url, json=payload)
data = resp.json()
print(data["message"]["content"])返回结构中，回答内容在message.content里，message.role固定为assistant。此外响应里还附带total_duration、prompt_eval_count等信息，方便做性能统计。如果要做多轮对话，只需把每一轮的assistant回复也追加进messages数组再发下一次请求即可。
二、OpenAI兼容接口：一行代码切换到本地模型
Ollama从早期版本开始就内置了/v1/chat/completions这个端点，完全遵循OpenAI的Chat Completions规范，同时还支持/v1/embeddings和/v1/models。这意味着所有依赖openai SDK的现有项目，只要修改两个参数就能跑在本地模型上：把base_url改成http://localhost:11434/v1，把api_key随便填一个非空字符串（比如ollama），再把模型名换成你本地已拉取的模型。
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama" # 本地服务不校验，但不能为空
)
response = client.chat.completions.create(
model="llama3",
messages=[
{"role": "user", "content": "用一句话解释什么是REST API"}
]
)
print(response.choices[0].message.content)这种方式的最大价值在于生态复用。比如你之前基于LangChain或LlamaIndex写的应用，底层调用的是OpenAI的接口，现在想换成私有化部署，只需要替换endpoint配置，业务代码一行都不用改。对于企业内网环境或者对数据隐私敏感的场景，这是成本最低的落地方案。
需要注意几个细节。第一，模型必须先通过ollama pull下载到本地，否则接口会返回404错误并提示模型不存在。第二，OpenAI SDK默认开启了流式以外的重试机制，如果本地模型加载较慢导致首包延迟过高，可能会触发超时，建议在创建client时调大timeout参数。第三，兼容接口支持的参数是子集，像temperature、top_p、max_tokens、stream都能用，但logprobs等高级参数会被忽略。
三、流式输出与嵌入接口的实战用法
流式输出对提升用户体验非常重要，特别是本地模型推理速度不如云端时，逐字输出能明显降低等待焦虑。原生API的流式模式会按行返回JSON，每行包含当前增量的message.content，最后一行的done字段为true。OpenAI兼容接口的流式则遵循SSE协议，用法和调用官方API完全一致：
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
stream = client.chat.completions.create(
model="llama3",
messages=[{"role": "user", "content": "写一首关于秋天的短诗"}],
stream=True
)
for chunk in stream:
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)嵌入接口在做RAG检索时必不可少，调用/api/embed或兼容端点/v1/embeddings都可以。做向量检索前记得使用专门的嵌入模型，例如nomic-embed-text，用对话模型生成向量效果会很差：
curl http://localhost:11434/api/embed -d '{
"model": "nomic-embed-text",
"input": "Ollama支持本地嵌入模型"
}'返回的embeddings数组就是文本的向量表示，维度取决于模型本身。这里有个容易踩的坑：如果之前用过旧版/api/embeddings接口，注意参数名从prompt换成了input，而且新接口支持批量传入，一次可以给一个字符串数组，性能比逐条调用好很多。
四、常见问题与排查思路
调用过程中最常见的问题是连接被拒绝，报错信息通常是Connection refused。这多半是Ollama服务没启动，执行ollama serve或直接运行任意模型即可拉起服务。如果服务在其他机器上，需要设置环境变量OLLAMA_HOST为0.0.0.0让Ollama监听所有网卡，同时注意防火墙放行11434端口。
第二个高频问题是中文乱码或者回答质量差。这不是API的问题，而是模型选择的问题，部分小参数模型对中文支持很弱，建议优先选用qwen系列或专门的多语言模型。第三个问题是首次请求特别慢，原因是模型需要从磁盘加载到显存，后续请求会复用已加载的模型，可以通过OLLAMA_KEEP_ALIVE环境变量控制模型在内存中的驻留时间，默认5分钟，设置为-1则常驻不卸载。
最后建议在生产环境里不要直接暴露Ollama端口到公网，它本身没有鉴权机制，任何拿到地址的人都能调用甚至删除模型。稳妥的做法是用Nginx做反向代理并加一层API Key校验，或者只在内网使用。理解了这套API的设计之后，你会发现把本地模型集成进自己的工具链其实非常简单。
Ollama APIOpenAI兼容接口REST调用修改时间：2026-09-12 08:24:31