Skip to main content

@llm_function

@llm_function 将 Python 函数签名转化为完整的 LLM 调用。一个输入,一个类型化输出。没有历史记录、没有工具(或带自动循环的工具)、没有状态管理。

基本用法

系统提示词的构建方式

你的文档字符串是起点,但框架会对其进行增强:
  1. 你的文档字符串 → 任务策略、质量标准、约束条件
  2. 参数类型 → 自动为模型生成描述
  3. 返回类型的 schema → 输出格式说明(基于 XML 的结构化提取)
  4. 工具最佳实践 → 挂载工具时会自动添加到提示词前部
你只需要编写模型应该做什么,框架负责处理模型应该输出什么

返回类型

Pydantic 模型(推荐用于结构化输出)

框架会根据 Pydantic 模型生成 XML schema,并指示模型生成匹配的输出。解析过程是自动的。

纯 str(用于自由格式文本)

列表和嵌套类型

基本类型

模板参数

在运行时向文档字符串注入动态值:

多模态图片参数

@llm_function 对图片输入保持普通 Python 函数形态:在函数签名里显式声明图片参数。
ImgUrl 用于网络 URL 或 data: URL。ImgPath 用于本地文件,框架会在发送给模型前编码为 data URL。多张图片应表达为显式参数,或 list[ImgUrl] / list[ImgPath] 这样的类型化列表。

搭配工具使用

@llm_function 可以通过 ReAct 循环使用工具:
函数仍然返回单个类型化结果,但在内部模型可能会多次调用工具,最终才生成答案。 max_tool_calls 限制模型可以进行的工具调用次数。None 表示不限制。

事件流模式

@llm_function 返回 LLMFunction callable instance。普通调用使用 await fn(...);需要 ReactOutput 时使用 fn.stream(...)
如果只需要最终响应,可以简化处理:

AbortSignal

取消正在执行的调用:

参数参考

调用时的特殊参数(以 _ 为前缀):
  • _template_params: Dict[str, Any] — 用于文档字符串格式化的模板值
  • _abort_signal: AbortSignal — 取消信号
API 参考:装饰器