示例代码

本章节收集了 SimpleLLMFunc 框架的各种使用示例。这些示例展示了框架的核心功能和最佳实践。

快速入口：可先查看 examples/README.md，其中包含按场景整理后的可运行命令（含无需 API Key 的本地示例）。

⚠️ 重要提示：本框架中的所有装饰器（@llm_function、@llm_chat、@tool）均要求被装饰的函数使用 async def 定义，并在调用时通过 await（或 asyncio.run）执行。

基础示例

llm_function 结构化输出（Pydantic）

文件: examples/llm_function_pydantic_example.py

这个例子展示了如何使用 @llm_function 返回复杂 Pydantic 结构：

• 多层嵌套模型定义

• 自动结构化解析

• 类型安全返回值处理

动态模板参数

文件: examples/dynamic_template_demo.py

演示如何在调用时通过 _template_params 动态填充 DocString 模板：

• 一个函数适配多种任务

• 按角色/风格切换 Prompt

• 降低重复函数定义

llm_function 事件流 + Pydantic

文件: examples/llm_function_event_pydantic.py

展示 @llm_function(enable_event=True) 的事件流与结构化输出协同：

• 捕获 LLM 调用事件

• 观察执行统计

• 处理最终结构化结果

高级示例

事件流观测示例

文件: examples/event_stream_chatbot.py

⭐ 全新功能！ 展示如何使用 SimpleLLMFunc v0.5.0+ 的事件流功能构建功能完整的聊天机器人。

核心特性：

• ✨ 实时流式响应：使用 Rich 库渲染 Markdown 格式的响应

• 🔧 工具调用可视化：实时显示工具调用的参数、执行过程和结果

• 📊 完整执行统计：Token 使用量、执行耗时、调用次数等详细信息

• 🎯 事件驱动架构：在外部函数中处理事件，实现自定义 UI 和逻辑

• 🧭 Origin 元数据路由：通过 output.origin 区分主链路与 fork 子链路

关键代码片段：

from SimpleLLMFunc import llm_chat
from SimpleLLMFunc.hooks import (
    ReactOutput, ResponseYield, EventYield,
    ReactStartEvent, LLMChunkArriveEvent, ToolCallStartEvent
)

# 启用事件流
@llm_chat(
    llm_interface=llm,
    toolkit=[calculate, get_weather, search_knowledge],
    stream=True,
    enable_event=True,  # 🔑 启用事件流
)
async def chat(user_message: str, chat_history: List[Dict[str, str]] = None):
    """智能助手"""
    pass

# 在外部处理事件
async for output in chat(user_message="帮我计算 25 * 4 + 18"):
    if isinstance(output, EventYield):
        # 处理事件：LLM 调用、工具调用等
        event = output.event
        origin = output.origin
        if origin.fork_id:
            print(f"fork={origin.fork_id} depth={origin.fork_depth}")
        if isinstance(event, ToolCallStartEvent):
            print(f"工具调用: {event.tool_name}")
            print(f"参数: {event.arguments}")
    
    elif isinstance(output, ResponseYield):
        # 原始响应对象（流式时为 chunk）。
        # 文本渲染建议使用 LLMChunkArriveEvent 的 accumulated_content。
        messages = output.messages

依赖安装：

pip install rich

运行示例：

python examples/event_stream_chatbot.py

详细文档：了解更多事件流的使用方法，请参考 事件流系统。

开箱即用终端 TUI

文件: examples/tui_chat_example.py

展示 @tui 与 @llm_chat 叠加后的终端体验：

• 聊天输入循环（底部输入框）

• 模型流式输出 + Markdown 渲染

• 灰色 reasoning delta（模型支持时）

• 工具调用参数/结果可视化

• 自定义 tool event hook（custom_event_hook）

• 示例同时注册 PyRepl（execute_code）与 batch_process，演示内置 hook + 自定义 hook

核心写法：

@tui(custom_event_hook=[my_hook])
@llm_chat(..., stream=True, enable_event=True)
async def agent(message: str, history=None):
    ...

if __name__ == "__main__":
    agent()

Run:

poetry run python examples/tui_chat_example.py

Runtime memory primitives (local, no model)

File: examples/runtime_primitives_basic_example.py

Shows how to use runtime primitives without any LLM provider:

• Start PyRepl with its builtin selfref backend and access it through repl.get_runtime_backend("selfref")

• Declare one custom PrimitivePack (constants.get) as extension example

• Perform CRUD operations through runtime.selfref.history.*

• Persist durable preferences into system prompt via runtime.selfref.history.append_system_prompt(...)

Run:

poetry run python examples/runtime_primitives_basic_example.py

General TUI Agent (selfref + file tools)

File: examples/tui_general_agent_example.py

Recommended single entry for a TUI-first agent workflow:

• One agent uses both runtime.selfref.history.* and runtime.selfref.fork.*

• FileToolset provides read/grep/sed/echo tools scoped to the workspace

• llm_chat injects runtime primitive guidance through tool-owned best practices (when PyRepl is mounted)

• Forked contexts inherit parent memory snapshot from the same selfref key

• Built-in lifecycle stream events (selfref_fork_start/spawned/end/error, selfref_fork_stream_*) are rendered in TUI

• Workspace is scoped to ./sandbox under the project root

Run:

poetry run python examples/tui_general_agent_example.py

Agent as a tool (stacked decorators)

文件: examples/agent_as_tool_example.py

展示如何把一个 LLM 驱动的 specialist 暴露成另一个 agent 的工具：

• @tool 外层 + @llm_function 内层，将 child agent 暴露进 toolkit

• parent @llm_chat 作为 supervisor，负责路由和最终答复

• child agent 保持独立 prompt / 职责边界，适合 reviewer / planner / router 组合

• 当前推荐子 agent 使用 @llm_function(enable_event=False)；若要复用 @llm_chat，通常需要先手写一层 wrapper tool

Run:

poetry run python examples/agent_as_tool_example.py

llm_function 事件流与 Token 用量监控

文件: examples/llm_function_token_usage.py

展示如何在 @llm_function 中使用事件流来实时监控 Token 使用情况。适用于需要精确计量 API 调用成本的场景。

核心特性：

• 🔍 实时 Token 监控：捕获每次 LLM 调用的 Token 用量

• 💰 成本追踪：记录 Prompt、Completion 和总 Token 数

• 📊 统计汇总：自动累计总用量

• ⚡ 零工具调用：简单的单次 LLM 调用示例

关键代码片段：

from SimpleLLMFunc import llm_function
from SimpleLLMFunc.hooks.events import LLMCallEndEvent
from SimpleLLMFunc.hooks.stream import is_response_yield

@llm_function(
    llm_interface=llm,
    enable_event=True,  # 🔑 启用事件流
)
async def summarize_text(text: str) -> str:
    """将给定的文本进行简洁的摘要"""
    return ""

# 捕获 Token 用量
async for output in summarize_text(text="..."):
    if is_response_yield(output):
        # 处理响应结果
        print(output.response)
    else:
        event = output.event
        if isinstance(event, LLMCallEndEvent):
            # 获取 Token 用量
            usage = event.usage
            if usage:
                print(f"Prompt Tokens: {usage.prompt_tokens}")
                print(f"Completion Tokens: {usage.completion_tokens}")
                print(f"Total Tokens: {usage.total_tokens}")

运行示例：

poetry run python examples/llm_function_token_usage.py

llm_chat 事件流聊天应用

文件: examples/event_stream_chatbot.py

展示如何使用 @llm_chat + 事件流构建完整对话应用：

• 多轮对话历史管理

• 流式响应与事件并行消费

• 工具调用可视化与统计

自定义 Tool 事件

文件: examples/custom_tool_event_example.py

演示在工具执行期间发射并消费自定义事件：

• ToolEventEmitter 进度事件上报

• CustomEvent 消费与渲染

• 批处理任务过程可视化

并行工具调用

文件: examples/parallel_toolcall_example.py

演示高级的工具调用特性：

• 多个工具的并行执行

• 工具调用的优化和性能

• 大规模工具集的管理

多模态内容处理

文件: examples/multi_modality_toolcall.py

展示多模态功能的使用：

• 图片 URL (ImgUrl) 的处理

• 本地图片路径 (ImgPath) 的处理

• 文本和图片的混合输入输出

供应商配置示例

Provider 配置文件

文件: examples/provider.json

示范 provider.json 的完整配置结构（提供商 -> 模型配置列表）：

• model_name 作为索引键

• API 密钥、重试与限流参数

• 适配任意 OpenAI 兼容服务

Provider 模板

文件: examples/provider_template.json

提供可复用的配置模板：

• 多供应商示例与参数说明

• 多密钥负载均衡

• 限流与重试最佳实践

按功能分类的示例

文本处理

• 结构化提取: 见 llm_function_pydantic_example.py

• 动态模板: 见 dynamic_template_demo.py

• 事件流监控: 见 llm_function_token_usage.py

工具调用

• 内置 REPL 工具调用: 见 pyrepl_example.py

• 多工具并行调用: 见 parallel_toolcall_example.py

• Agent as a Tool: 见 agent_as_tool_example.py

对话与 Agent

• 事件流聊天: 见 event_stream_chatbot.py

• 自定义工具事件: 见 custom_tool_event_example.py

• 终端 TUI 聊天: 见 tui_chat_example.py

• 事件流观测: 见 event_stream_chatbot.py ⭐ 使用 enable_event=True 实时观察 ReAct 循环执行过程

多模态处理

• 图片分析: 见 multi_modality_toolcall.py

• 混合输入输出: 见 multi_modality_toolcall.py

快速运行示例

前置要求

1. 安装 SimpleLLMFunc: pip install SimpleLLMFunc

2. 配置 API 密钥（见 快速开始）

3. 创建或编辑 provider.json 文件

运行方式

# 进入 examples 目录
cd examples

# 运行基础 LLM 函数示例
python llm_function_pydantic_example.py

# 运行聊天示例
python event_stream_chatbot.py

# 运行并行工具调用示例
python parallel_toolcall_example.py

# 运行多模态示例
python multi_modality_toolcall.py

# 运行事件流 Chatbot 示例（需要先安装 rich: pip install rich）
python event_stream_chatbot.py

# 运行 Textual TUI 示例
python tui_chat_example.py

完整的 Examples 目录

所有示例代码都位于仓库的 examples/ 目录中：

仓库链接: https://github.com/NiJingzhe/SimpleLLMFunc/tree/master/examples

在该目录中你可以找到：

• 各种装饰器的使用示例

• 不同 LLM 供应商的配置示例

• 最佳实践的参考实现

• 环境变量配置的示例

学习路径建议

初级用户

1. 阅读 快速开始 文档

2. 运行 llm_function_pydantic_example.py

3. 修改示例代码，尝试自己的 Prompt

中级用户

1. 学习 llm_chat 装饰器文档

2. 运行 event_stream_chatbot.py

3. 尝试 parallel_toolcall_example.py

高级用户

1. 阅读 LLM 接口层文档

2. 学习多模态处理：multi_modality_toolcall.py

3. 学习事件流处理：event_stream_chatbot.py ⭐

4. 自定义 LLM 接口和工具系统

常见问题

Q: 示例代码在哪里？

A: 所有示例代码都在 GitHub 仓库的 examples/ 目录中。你可以直接查看或下载运行。

Q: 如何修改示例代码？

A:

1. 克隆仓库：git clone https://github.com/NiJingzhe/SimpleLLMFunc.git

2. 编辑 examples/ 目录中的文件

3. 运行修改后的代码

Q: 示例是否支持所有 LLM 供应商？

A: 示例代码使用 provider.json 配置，支持任何兼容 OpenAI API 的供应商。参考 provider_template.json 配置你的供应商。

Q: 我遇到了问题，该怎么办？

A:

1. 检查 快速开始 中的配置部分

2. 查看详细的 使用指南

3. 在 GitHub 提交 Issue：https://github.com/NiJingzhe/SimpleLLMFunc/issues

贡献新示例

如果你想为项目贡献新的示例代码：

1. Fork 仓库

2. 在 examples/ 目录中创建新文件

3. 遵循现有示例的代码风格和注释

4. 提交 Pull Request

详细信息见 贡献指南。

相关资源

• 官方仓库: https://github.com/NiJingzhe/SimpleLLMFunc

• 完整文档: https://simplellmfunc.readthedocs.io/

• 发布日志: https://github.com/NiJingzhe/SimpleLLMFunc/releases

• 问题反馈: https://github.com/NiJingzhe/SimpleLLMFunc/issues