大模型应用开发 / 系统课时
调用文本生成接口
调用文本生成接口
学习目标
完成本课后,你将能够:
- 使用
/api/generate完成单轮文本生成- 设置提示词、运行参数和非流式返回
- 解析回答、Token 计数和耗时字段
- 处理模型不存在、超时和无效 JSON 等异常
接口适用范围
POST /api/generate 面向单个提示词生成。它适合摘要、改写、分类、抽取、单轮问答和非对话式自动化任务。需要角色化多轮消息时,应使用 /api/chat。
最小请求
执行:
bash
curl --fail --silent --show-error http://localhost:11434/api/generate -H "Content-Type: application/json" -d '{
"model": "gemma3:1b",
"prompt": "用一句话解释 Ollama。",
"stream": false
}'预期响应结构:
json
{
"model": "gemma3:1b",
"created_at": "<TIMESTAMP>",
"response": "<MODEL_RESPONSE>",
"done": true,
"done_reason": "<DONE_REASON>",
"total_duration": 0,
"load_duration": 0,
"prompt_eval_count": 0,
"prompt_eval_duration": 0,
"eval_count": 0,
"eval_duration": 0
}所有时间和计数均为动态值,示例中的 0 只表示数值字段。
设置运行参数
执行:
bash
curl --fail --silent --show-error http://localhost:11434/api/generate -H "Content-Type: application/json" -d '{
"model": "gemma3:1b",
"prompt": "列出本地部署模型的三个检查项。",
"stream": false,
"keep_alive": "10m",
"options": {
"temperature": 0,
"seed": 42,
"num_ctx": 4096,
"num_predict": 120
}
}'预期结果:
text
HTTP 200;response 为非空文本;done 为 true;统计字段存在。Python 完整调用
保存为 generate_once.py:
python
import json
import urllib.error
import urllib.request
URL = "http://localhost:11434/api/generate"
payload = {
"model": "gemma3:1b",
"prompt": "用三个要点说明本地模型的适用场景。",
"stream": False,
"options": {
"temperature": 0,
"num_predict": 160,
},
}
request = urllib.request.Request(
URL,
data=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request, timeout=180) as response:
result = json.load(response)
except urllib.error.HTTPError as exc:
error_body = exc.read().decode("utf-8", errors="replace")
raise SystemExit(f"HTTP {exc.code}: {error_body}") from exc
except urllib.error.URLError as exc:
raise SystemExit(f"无法连接 Ollama: {exc.reason}") from exc
print(result["response"].strip())
print(f"done={result['done']}")
print(f"prompt_tokens={result.get('prompt_eval_count', 0)}")
print(f"output_tokens={result.get('eval_count', 0)}")运行:
bash
python generate_once.py预期输出结构:
text
<MODEL_RESPONSE>
done=True
prompt_tokens=<COUNT>
output_tokens=<COUNT>计算输出速度
若 eval_duration 大于零:
text
输出 Token/s
= eval_count ÷ (eval_duration ÷ 1,000,000,000)如果模型刚加载,total_duration 会包含明显的 load_duration。不要用总耗时直接替代纯生成速度。
控制停止与长度
num_predict 控制最大输出 Token。模型也可能因为结束标记、停止序列、上下文满或客户端取消而提前结束。应读取 done_reason,而不是只检查文本长度。
对于必须完整输出的 JSON 或代码,过小的 num_predict 可能造成截断。
异常处理
常见异常:
- 连接拒绝:服务未启动或地址错误。
- HTTP 404:模型名称或端点错误。
- HTTP 400:JSON 字段或类型错误。
- HTTP 503:服务繁忙或队列已满。
- 客户端超时:模型加载、长输入或生成耗时超过设置。
response为空:预加载请求、模型行为或停止条件导致。
客户端应记录状态码、错误体、模型、参数和请求 ID,不要只显示“调用失败”。
本课练习
练习 1:封装生成函数
任务目标:实现可复用单轮调用。输入或初始条件:Python 3 和 Ollama 可用。实现要求:封装模型、提示词、超时和参数。验收条件:连接错误与 HTTP 错误有不同提示。
练习 2:分析性能字段
任务目标:计算生成吞吐。输入或初始条件:完成一次非流式请求。实现要求:计算输入和输出 Token/s。验收条件:单位从纳秒正确转换为秒。
练习 3:验证输出截断
任务目标:理解 num_predict。输入或初始条件:准备需要较长回答的提示词。实现要求:使用小值与大值对比
验收条件:能结合 done_reason 判断是否截断。
按自己的节奏,确认真正理解。