smartfunc

使用 OpenAI SDK 将函数转换为由大语言模型驱动的端点

安装

uv pip install smartfunc

这是什么？

以下是一个使用该库可以实现的示例：

from smartfunc import backend
from openai import OpenAI

client = OpenAI()

@backend(client, model="gpt-4o-mini")
def generate_summary(text: str) -> str:
    return f"Generate a summary of the following text: {text}"

现在，generate_summary 函数将返回您提供的文本摘要。

其他提供商

请注意，我们在这里使用的是 OpenAI SDK，但这并不意味着您必须使用他们的 LLM 服务。如今，OpenAI SDK 已成为一种标准，支持许多（如果不是大多数）提供商，包括用于本地模型的 Ollama，以及许多云托管提供商，如 OpenRouter。只需在调用 OpenAI() 时手动设置 api_key 和 base_url 参数即可。

OpenAI(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    base_url="https://openrouter.ai/api/v1"
)

工作原理是什么？

该库使用 OpenAI SDK 与 LLM 进行交互。您的函数可以返回字符串（作为提示）或消息字典列表（以实现完全的对话控制）。装饰器负责调用 LLM 并解析响应。

这种方法的主要优势：

• 适用于任何兼容 OpenAI SDK 的提供商：可使用 OpenAI、OpenRouter 或任何具有 OpenAI 兼容 API 的提供商
• 完全的 Python 控制：使用 Python 构建提示（无需学习模板语法）
• 类型安全的结构化输出：使用 Pydantic 模型获取经过验证的响应
• 异步支持：内置 async/await 支持，并发操作
• 对话历史记录：传递消息列表以进行多轮对话
• 多模态支持：通过 base64 编码包含图像、音频和视频
• 简单而专注：专注于一件事——将函数转换为 LLM 调用

功能

基本用法

使用 smartfunc 的最简单方式：

from smartfunc import backend
from openai import OpenAI

client = OpenAI()

@backend(client, model="gpt-4o-mini")
def write_poem(topic: str) -> str:
    return f"Write a short poem about {topic}"

print(write_poem("summer"))

结构化输出

使用 Pydantic 模型获取经过验证的结构化响应：

from smartfunc import backend
from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Summary(BaseModel):
    summary: str
    pros: list[str]
    cons: list[str]

@backend(client, model="gpt-4o-mini", response_format=Summary)
def analyze_pokemon(name: str) -> str:
    return f"Describe the following pokemon: {name}"

result = analyze_pokemon("pikachu")
print(result.summary)
print(result.pros)
print(result.cons)

这将返回一个 Pydantic 模型，可能如下所示：

Summary(
    summary='Pikachu is a small, electric-type Pokémon...',
    pros=['Iconic mascot', 'Strong electric attacks', 'Cute appearance'],
    cons=['Weak against ground-type moves', 'Limited evolution options']
)

系统提示和参数

您可以在客户端提前确认任何内容。

@backend(
    client,
    model="gpt-4o-mini",
    response_format=Summary,
    system="You are a Pokemon expert with 20 years of experience",
    temperature=0.7,
    max_tokens=500
)
def expert_analysis(pokemon: str) -> Summary:
    return f"Provide an expert analysis of {pokemon}"

异步支持

如果您喜欢异步工作，可以使用 async_backend 进行非阻塞操作。请注意，如果发送请求过快，可能会被 LLM 提供商限流。

import asyncio
from smartfunc import async_backend
from openai import AsyncOpenAI

client = AsyncOpenAI()

@async_backend(client, model="gpt-4o-mini", response_format=Summary)
async def analyze_async(pokemon: str) -> Summary:
    return f"Describe: {pokemon}"

result = asyncio.run(analyze_async("charizard"))
print(result)

复杂的提示逻辑

由于提示是用 Python 构建的，您可以使用任何逻辑：

@backend(client, model="gpt-4o-mini")
def custom_prompt(items: list[str], style: str, include_summary: bool) -> str:
    """Generate with custom logic."""
    prompt = f"Write in {style} style:\n\n"

    for i, item in enumerate(items, 1):
        prompt += f"{i}. {item}\n"

    if include_summary:
        prompt += "\nProvide a brief summary at the end."

    return prompt

result = custom_prompt(
    items=["First point", "Second point", "Third point"],
    style="formal",
    include_summary=True
)

对话历史

除了返回字符串外，您还可以返回消息字典列表，以完全控制对话：

@backend(client, model="gpt-4o-mini")
def chat_with_history(user_message: str, conversation_history: list) -> list:
    """Chat with conversation context."""
    messages = [
        {"role": "system", "content": "You are a helpful assistant."},
    ]

    # Add previous conversation
    messages.extend(conversation_history)

    # Add new user message
    messages.append({"role": "user", "content": user_message})

    return messages

# Use it with conversation history
history = [
    {"role": "user", "content": "What's your name?"},
    {"role": "assistant", "content": "I'm Claude, an AI assistant."},
]

response = chat_with_history("What can you help me with?", history)
print(response)

注意：当您返回消息列表时，装饰器中的 system 参数将被忽略。

多模态内容（图像、音频、视频）

您可以通过在消息中以 base64 编码的形式传递图像、音频或视频来包含这些内容：

import base64

@backend(client, model="gpt-4o-mini")
def analyze_image(image_path: str, question: str) -> list:
    """用问题分析一张图像。"""
    # 读取并编码图像
    with open(image_path, "rb") as f:
        image_data = base64.b64encode(f.read()).decode("utf-8")

    return [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": question},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    },
                },
            ],
        }
    ]

result = analyze_image("photo.jpg", "这张图里有什么？")
print(result)

您还可以混合使用多种媒体类型：

@backend(client, model="gpt-4o-mini")
def analyze_multiple_media(image1_path: str, image2_path: str) -> list:
    """比较两张图像。"""
    # 编码图像
    with open(image1_path, "rb") as f:
        img1 = base64.b64encode(f.read()).decode("utf-8")
    with open(image2_path, "rb") as f:
        img2 = base64.b64encode(f.read()).decode("utf-8")

    return [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "比较这两张图像："},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{img1}"},
                },
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{img2}"},
                },
            ],
        }
    ]

result = analyze_multiple_media("image1.jpg", "image2.jpg")

对于音频内容：

@backend(client, model="gpt-4o-mini")
def transcribe_audio(audio_path: str) -> list:
    """转录音频内容。"""
    with open(audio_path, "rb") as f:
        audio_data = base64.b64encode(f.read()).decode("utf-8")

    return [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请转录这段音频："},
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": audio_data,
                        "format": "wav"  # 或 "mp3"、"flac" 等
                    },
                },
            ],
        }
    ]

使用 OpenRouter

OpenRouter 提供了一个与 OpenAI 兼容的 API，可访问数百种模型：

from openai import OpenAI
import os

# OpenRouter 客户端
openrouter_client = OpenAI(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    base_url="https://openrouter.ai/api/v1"
)

# 通过 OpenRouter 使用 Llama 模型
@backend(openrouter_client, model="meta-llama/llama-3.1-70b", response_format=Summary)
def analyze_with_llama(pokemon: str) -> Summary:
    return f"分析 {pokemon}"

可重用的后端配置

您可以创建可重用的后端配置：

from smartfunc import backend
from openai import OpenAI

client = OpenAI()

# 创建一个配置好的后端
gpt_mini = lambda **kwargs: backend(
    client,
    model="gpt-4o-mini",
    system="你是一位乐于助人的助手",
    temperature=0.7,
    **kwargs
)

# 多次使用
@gpt_mini(response_format=Summary)
def summarize(text: str) -> Summary:
    return f"总结：{text}"

@gpt_mini()
def translate(text: str, language: str) -> str:
    return f"将 '{text}' 翻译成 {language}"

从 v0.2.0 迁移

from smartfunc import backend

@backend("gpt-4o-mini")
def summarize(text: str) -> Summary:
    """总结：{{ text }}"""
    pass

from smartfunc import backend
from openai import OpenAI

client = OpenAI()

@backend(client, model="gpt-4o-mini", response_format=Summary)
def summarize(text: str) -> Summary:
    """这现在是实际的文档说明。"""
    return f"总结：{text}"

开发

运行测试：

make check

或者：

uv run pytest tests

smartfunc 快速上手指南

smartfunc 是一个轻量级 Python 库，旨在通过装饰器将普通 Python 函数直接转换为由大语言模型（LLM）驱动的智能端点。它基于 OpenAI SDK 构建，支持所有兼容该标准的提供商（如 OpenAI、OpenRouter、Ollama 等）。

环境准备

• Python 版本：建议 Python 3.9+
• 前置依赖：
  • openai SDK（用于连接 LLM 服务）
  • pydantic（可选，用于结构化输出验证）
• API Key：需准备对应 LLM 服务商的 API Key（如 OpenAI Key 或 OpenRouter Key）

国内开发者提示：若使用 OpenAI 官方服务可能需要网络代理。推荐尝试使用 OpenRouter 或本地部署的 Ollama，它们均兼容 OpenAI SDK 接口，配置更灵活。

安装步骤

推荐使用 uv 进行快速安装（也可使用 pip）：

uv pip install smartfunc

或者使用标准 pip 安装：

pip install smartfunc

确保同时安装了必要的依赖库：

pip install openai pydantic

基本使用

1. 初始化客户端

首先导入 OpenAI 客户端并配置 API Key。

from smartfunc import backend
from openai import OpenAI
import os

# 配置 OpenAI 客户端
client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY") # 请确保环境变量中已设置 KEY
)

多提供商支持：若使用 OpenRouter 或其他兼容服务，只需修改 base_url 和 api_key：

client = OpenAI(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    base_url="https://openrouter.ai/api/v1"
)

2. 定义智能函数

使用 @backend 装饰器包裹普通函数。函数返回值将作为 Prompt 发送给 LLM，装饰器会自动处理调用并返回结果。

@backend(client, model="gpt-4o-mini")
def write_poem(topic: str) -> str:
    return f"Write a short poem about {topic}"

# 调用函数
result = write_poem("summer")
print(result)

3. 结构化输出（进阶）

结合 Pydantic 模型，可强制 LLM 返回格式严格的 JSON 数据，并自动转换为 Python 对象。

from pydantic import BaseModel

class Analysis(BaseModel):
    summary: str
    keywords: list[str]

@backend(client, model="gpt-4o-mini", response_format=Analysis)
def analyze_text(text: str) -> Analysis:
    return f"Analyze the following text and extract keywords: {text}"

result = analyze_text("Artificial Intelligence is transforming the world.")
print(result.summary)
print(result.keywords)

4. 异步支持

如需高并发场景，可使用 async_backend 和 AsyncOpenAI 客户端。

import asyncio
from smartfunc import async_backend
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

@async_backend(async_client, model="gpt-4o-mini")
async def quick_summarize(text: str) -> str:
    return f"Summarize: {text}"

# 运行异步函数
result = asyncio.run(quick_summarize("Hello world"))
print(result)