执行你的首次生成调用

Kerb 工具包让你轻松地对模型进行首次调用，简化了文本生成过程。它提供了一个统一的函数 generate()，作为所有文本生成任务的主要接口，不论底层服务商是谁。这种设计让你只需编写一次应用逻辑，然后通过更改几个参数 (parameter)，即可轻松地在 OpenAI、Anthropic、Google 或其他模型之间切换。

生成函数

generate() 函数是与 LLM 交互的主要入口点。它抽象了 API 调用的服务商特定细节，例如请求格式和认证，让你能专注于应用逻辑。

最简单的用法是，你可以将字符串提示传递给该函数。让我们进行首次调用来生成一首短诗。

from kerb.generation import generate, ModelName, LLMProvider

# 对 OpenAI 的 GPT-4o-mini 模型进行生成调用
response = generate(
    "写一首关于 Python 代码的三行短诗。",
    model=ModelName.GPT_4O_MINI,
    provider=LLMProvider.OPENAI
)

# 生成的文本位于 'content' 属性中
print(response.content)

在此示例中，我们提供了三个主要参数 (parameter)：

• 以简单字符串形式提供的提示。
• 模型标识符，使用 ModelName 枚举以求清晰并避免拼写错误。
• 服务商，使用 LLMProvider 枚举指定。

这个单一的函数调用处理整个流程：它从你的配置中找到正确的 API 密钥，为指定服务商格式化请求，发送请求，并将响应解析成标准化对象。

理解响应对象

generate() 函数返回一个结构化的 GenerationResponse 对象，而不仅仅是原始文本。此对象包含关于 API 调用的宝贵元数据，对于调试、性能监控和成本追踪很有用。

让我们检查来自我们之前调用的响应对象的属性。

# 假设 'response' 是来自上一个示例的 GenerationResponse

print(f"所用模型: {response.model}")
print(f"服务商: {response.provider.value}")
print(f"输出文本:\n{response.content}")
print(f"延迟: {response.latency:.3f} 秒")

# 访问令牌使用量和成本信息
if response.usage:
    print(f"总令牌数: {response.usage.total_tokens}")
    print(f"输入令牌数: {response.usage.input_tokens}")
    print(f"输出令牌数: {response.usage.output_tokens}")

if response.cost is not None:
    print(f"预估成本: ${response.cost:.6f}")

这种结构化输出提供了几项益处：

• content: 模型生成的文本。
• model 和 provider: 确认是哪个模型和服务商处理了请求。
• latency: 测量 API 调用的持续时间，帮助你发现性能问题。
• usage: 提供令牌消耗的细分信息，这对于管理上下文 (context)窗口和预测成本来说必不可少。
• cost: 根据服务商的定价给出调用的预估成本，使监控应用开销变得更方便。

使用消息列表构建结构化提示

尽管简单的字符串对许多任务来说足够了，但大多数现代基于聊天的模型都针对结构化消息列表进行了优化。这种格式让你能够为对话的不同部分定义角色，例如系统指令、用户查询和之前的助手回复。该工具包通过 Message 对象来支持这一点。

下面是如何使用系统消息来构建提示以引导模型的行为，以及包含查询的用户消息。

from kerb.core import Message
from kerb.core.types import MessageRole

# 创建消息列表
messages = [
    Message(role=MessageRole.SYSTEM, content="你是一个有用的助手，用一句话解释编程概念。"),
    Message(role=MessageRole.USER, content="用 Python 解释什么是列表推导式。")
]

response = generate(
    messages,
    model=ModelName.GPT_4O_MINI,
    provider=LLMProvider.OPENAI
)

print(response.content)

使用消息列表是构建会话式应用的推荐方式，因为它提供了一种清晰有序的方式来管理对话历史。为了方便，你也可以使用包含 "role" 和 "content" 键的字典列表来代替 Message 对象。

控制生成参数 (parameter)

你可以通过向 generate() 函数传递额外参数来影响模型的输出。最常见的两个参数是 temperature 和 max_tokens。

• temperature: 一个介于 0 到 2 之间的值，用于控制随机性。较低的值（例如 0.2）使输出更具确定性和集中性，而较高的值（例如 0.8）则使其更具创造性和多样性。
• max_tokens: 响应中要生成的最大令牌数。这有助于控制输出的长度并管理成本。

response = generate(
    "写一个关于一个学习绘画的机器人的创意短故事，一段话即可。",
    model=ModelName.GPT_4O_MINI,
    provider=LLMProvider.OPENAI,
    temperature=0.8,  # 较高的 temperature 值可获得更多创意
    max_tokens=150      # 限制故事的长度
)

print(response.content)

为了管理多个参数，你可以使用 GenerationConfig 对象。这让你能够定义一组可重用的参数，用于应用的不同部分，确保一致性。

from kerb.generation import GenerationConfig

# 创建可重用配置
config = GenerationConfig(
    temperature=0.2,
    max_tokens=100,
    top_p=0.9
)

response = generate(
    "什么是 API？",
    model=ModelName.GPT_4O_MINI,
    provider=LLMProvider.OPENAI,
    config=config
)

print(response.content)

在不同服务商之间切换

统一接口的一大优点是，能够以最少的代码改动在不同 LLM 服务商之间切换。这对于模型 A/B 测试、为特定任务选择最具成本效益的选项，或为你的应用增加冗余都很有价值。

例如，从 OpenAI 模型切换到 Anthropic 模型，就像更改 model 和 provider 参数 (parameter)一样简单。

# 使用 OpenAI 模型进行调用
response_openai = generate(
    "列举使用 Python 的三个优点。",
    model=ModelName.GPT_4O_MINI,
    provider=LLMProvider.OPENAI
)
print(f"OpenAI 响应:\n{response_openai.content}\n")

# 使用 Anthropic 模型进行调用
try:
    response_anthropic = generate(
        "列举使用 Python 的三个优点。",
        model=ModelName.CLAUDE_35_HAIKU,
        provider=LLMProvider.ANTHROPIC
    )
    print(f"Anthropic 响应:\n{response_anthropic.content}")
except Exception as e:
    print(f"无法调用 Anthropic API: {e}")

有了这个基础，你现在可以可靠地从任何受支持的 LLM 生成文本。在下一节中，我们将介绍如何处理流式响应，这对于创建实时、交互式应用（如聊天机器人）很重要。