4.3 SDK 与多语言支持

4.3 SDK 与多语言支持

本节摘要：Ollama 是"协议优先"的——官方 SDK 只是对 REST 端点的薄封装，因此每种语言都能在百行以内获得完整能力。本节给出 Python（ollama 库）与 JavaScript（ollama npm 包）的实战代码，再比较"官方薄封装 / OpenAI 兼容层 / 直接 HTTP"三条接入路线的选择依据，最后覆盖 Java、Go、Rust 等社区生态。

Python：ollama 官方库

pip install ollama 后，chat、generate、embed、list、pull、show 与 REST 端点一一对应。一段代码覆盖最常见的需求：

import ollama

# 1) 单轮生成
r = ollama.generate(model="qwen2.5:7b",
                    prompt="把这句话改成更口语的中文：请务必于今日内反馈",
                    options={"temperature": 0.3})
print(r["response"])

# 2) 多轮对话（历史自己维护）
messages = [{"role": "system", "content": "你是 Python 代码评审员"}]
messages.append({"role": "user", "content": "这段代码有什么风险：time.sleep(1/0)"})
ans = ollama.chat(model="qwen2.5:7b", messages=messages)["message"]["content"]
messages.append({"role": "assistant", "content": ans})
​

流式在 Python 侧是生成器，逐块拿到增量：

for part in ollama.chat(model="qwen2.5:7b",
                        messages=[{"role": "user", "content": "写一首关于硬盘噪声的俳句"}],
                        stream=True):
    print(part["message"]["content"], end="", flush=True)
​

结构化输出直接把 JSON Schema 当 format 传入，返回内容是符合 schema 的 JSON 字符串，json.loads 后即可当字典用：

import json
from pydantic import BaseModel

class Task(BaseModel):
    title: str
    priority: int

schema = Task.model_json_schema()
out = ollama.chat(model="qwen2.5:7b",
                  format=schema,
                  options={"temperature": 0},
                  messages=[{"role": "user",
                             "content": "从'周五前修完登录bug并写回归用例'提取任务"}])
task = Task(**json.loads(out["message"]["content"]))
print(task.title, task.priority)
​

嵌入同样一行：

e = ollama.embed(model="nomic-embed-text", input=["第一段", "第二段"])
print(len(e["embeddings"][0]))   # 768 维，视模型而定
​

JavaScript / TypeScript：ollama npm 包

npm install ollama 提供 chat、generate、embeddings 等方法，原生支持流式回调，写聊天界面时体感最好：

import { Ollama } from "ollama";

const ollama = new Ollama({ host: "http://localhost:11434" });

// 流式输出到终端
const stream = await ollama.chat({
  model: "qwen2.5:7b",
  messages: [{ role: "user", content: "用三行解释事件循环" }],
  stream: true,
});
for await (const part of stream) {
  process.stdout.write(part.message.content);
}
​

Node 之外，ollama-js 也能跑在浏览器（配合跨域配置）与 React Native 中，前提是 OLLAMA_ORIGINS 放行了页面来源（第 7.1 节详述）。

三条接入路线怎么选

路线 A：官方薄封装。 类型友好、跟随版本更新最快、暴露全部专有能力（如 format schema、keep_alive）。新项目默认选它。

路线 B：OpenAI 兼容层。 用 openai 官方客户端指向本地 Ollama 的 /v1 端点。最大好处是"同一份代码，本地与云端一键切换"——开发调试用本地小模型，上线换 base_url 指向付费 API，或反过来做降级备份。代价是只能用到两边能力的交集。

路线 C：裸 HTTP。 无依赖、任何语言可用、行为完全透明。嵌入脚本、CI 步骤、临时验证的最优选：

// Go：标准库即可，无需第三方 SDK
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":  "qwen2.5:7b",
		"prompt": "一句话说明什么是幂等",
		"stream": false,
	})
	resp, err := http.Post("http://localhost:11434/api/generate",
		"application/json", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var out struct{ Response string `json:"response"` }
	json.NewDecoder(resp.Body).Decode(&out)
	fmt.Println(out.Response)
}
​

其他语言的社区生态

Java 侧有 ollama4j：构造 OllamaAPI 并传入本机服务地址后即可 api.chat(...)，与 Spring AI 的集成也是基于它或直接 HTTP。Rust 有 ollama-rs，异步接口与 tokio 生态贴合。.NET 有 OllamaSharp，提供 OllamaApiClient 与 Microsoft.Extensions.AI 适配器。这些库成熟度不一，接入前看两点：是否支持流式与最新端点（如 /api/ps）、维护是否活跃。

共同注意事项有两条。其一，SDK 默认连 localhost:11434，容器或远程场景记得显式传 host。其二，所有 SDK 最终发的还是那几个 REST 请求——抓包（或日志）看到的流量和裸 curl 一致，因此"SDK 出问题"基本等于"请求拼错"，用 curl 复现是最快的定位法。

# 万能对照：任何 SDK 行为都可以用这条命令复现
curl http://localhost:11434/api/chat -d '{"model":"qwen2.5:7b","stream":false,"messages":[{"role":"user","content":"ping"}]}'
​

交互层的拼图到此完整：CLI 面向人、REST 面向协议、SDK 面向语言生态。接下来进入每个本地部署者都要面对的现实问题——硬件选型与性能调优。