第3章 Ollama的API兼容性概览

3、Ollama的API兼容性概览

好，咱们直接切入正题。这一章我打算聊聊Ollama API和OpenAI API到底哪里像、哪里不像。说白了，就是搞清楚Ollama这个"兼容层"到底是怎么工作的。我自己在对接各种大模型平台时，踩过不少坑，尤其是API参数不兼容的问题，折腾得够呛。所以这一章的内容，都是我实际摸爬滚打总结出来的。

先说说它们最核心的区别。OpenAI的API是一个商业产品，功能丰富，但有些限制。Ollama呢，它是开源的，主打本地部署。你想想看，一个在云端，一个在你自己的机器上，这天然就决定了它们的定位不同。

我举个例子。OpenAI的API有严格的速率限制，你调用太频繁会被429。Ollama呢？只要你的硬件扛得住，随便你怎么调。我在本地跑Ollama时，经常一次性发几十个请求做压力测试，完全不用担心被封。

但相似的地方也不少。Ollama在设计上刻意模仿了OpenAI的接口风格。为什么？因为开发者习惯了。你想想看，如果每个模型平台都搞一套自己的API规范，那开发者得疯掉。所以Ollama选择了兼容。

核心结论：Ollama不是完全复制OpenAI，而是做了一个"子集"。它支持OpenAI最常用的那些端点，但一些高级特性（比如微调、嵌入的批量处理）暂时没有。

这个兼容层，说白了就是一个"翻译官"。你的代码里写的是OpenAI的调用方式，Ollama在背后帮你转换成自己的内部调用。

具体怎么做的呢？我画了一张图，你看一眼就明白了。

你看，整个流程其实很清晰。你的应用代码用OpenAI的SDK发请求，Ollama的兼容层收到后，把参数做一次映射转换，然后交给自己的核心引擎去处理。处理完的结果，再按照OpenAI的格式包装一下返回。

嗯，这里要注意一点。这个兼容层不是万能的。有些OpenAI特有的参数，比如logprobs、suffix这些，Ollama目前是不支持的。我刚开始用的时候，传了个logprobs参数进去，结果Ollama直接忽略了，也没报错。这就有点坑了，因为你的代码可能不会察觉到参数没生效。

避坑提醒：我曾经在项目中遇到过一个bug，代码里设置了max_tokens，但Ollama那边用的是num_predict。如果你直接传max_tokens，Ollama会忽略它，使用默认值。所以一定要确认参数映射关系。

咱们来看看Ollama具体支持哪些端点。我整理了一个表格，方便你对照。

OpenAI端点	Ollama对应端点	支持状态	备注
`/v1/chat/completions`	`/v1/chat/completions`	✅ 完全支持	最常用的聊天接口
`/v1/completions`	`/v1/completions`	✅ 支持	文本补全接口
`/v1/embeddings`	`/v1/embeddings`	✅ 支持	需要模型支持嵌入
`/v1/models`	`/v1/models`	✅ 支持	列出本地模型
`/v1/images/generations`	❌ 不支持	❌	Ollama不支持图像生成
`/v1/audio/transcriptions`	❌ 不支持	❌	语音转文字暂不支持

从表格里能看出来，Ollama主要支持的是文本相关的接口。图像、音频这些多模态能力，目前还没有。不过话说回来，Ollama的定位就是本地LLM推理，这个范围已经够用了。

参数这块，我重点说说几个容易出问题的。

model参数：OpenAI用的是gpt-4、gpt-3.5-turbo这种命名。Ollama用的是llama3.2、mistral这种。格式不同，但逻辑一样。
stream参数：这个完全兼容。你传stream: true，Ollama会返回SSE流。我在做实时对话功能时，用的就是这个。
stop参数：兼容。但要注意，Ollama对stop序列的处理可能和OpenAI略有差异。我遇到过一个问题，同样的stop序列，OpenAI能准确停住，Ollama会多输出几个token。

小技巧：如果你不确定某个参数是否兼容，最简单的办法是直接试。Ollama会忽略不支持的参数，不会报错。但为了保险起见，我建议你在测试环境先跑一遍，看看返回结果是否符合预期。

最后说一句，Ollama的兼容层还在持续更新中。我记得去年的时候，它连/v1/models都不支持，现在都已经有了。所以如果你发现某个功能暂时没有，别急，说不定下个版本就加上了。

好了，这一章的内容就这些。核心就是记住：Ollama兼容了OpenAI最常用的接口，但有一些细微差别。用的时候多留个心眼，尤其是参数映射那块。