大模型应用开发 / 系统课时

调用文本生成接口

调用文本生成接口

学习目标

完成本课后,你将能够:

  • 使用 /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 判断是否截断。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

调用文本生成接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通