Marvin轻量AI工具库上手指南：给普通函数贴上“AI魔法贴”

可视化演示

\u5c55\u793a\u8bcd\u5d4c\u5165\u5c06\u8bcd\u8bed\u6620\u5c04\u5230\u8fde\u7eed\u5411\u91cf\u7a7a\u95f4\u7684\u8fc7\u7a0b\uff0c\u8bed\u4e49\u76f8\u8fd1\u7684\u8bcd\u5728\u7a7a\u95f4\u4e2d\u805a\u96c6\uff0c\u901a\u8fc7\u4f59\u5f26\u76f8\u4f3c\u5ea6\u8861\u91cf\u8bcd\u95f4\u5173\u7cfb\u3002

设计理念：一盒改变“苦力函数”的魔法贴纸

老张的面馆里，每张菜谱卡都写得清清楚楚：牛肉面用什么料、煮几分钟、加不加辣——这就是一个“普通函数”：输入固定、输出固定，一丝不苟，也一丝不变。顾客一句“多放辣”就把菜谱卡问懵了。后来老张得到一盒“魔法贴纸”，店员只需把贴纸往菜谱卡上一贴，菜谱卡就突然变得“通人性”——它能听懂人话、能根据客人需求自己调整做法。

这盒贴纸就是 Marvin。Marvin 的核心设计理念是“声明式 AI”：你不需要手把手告诉程序每一步怎么调用大模型、怎么拼接提示词、怎么解析返回结果，你只需要用装饰器“声明”某个函数是 AI 函数，剩下的交给他。这种理念和传统命令式编程恰恰相反——你不用关心“怎么做”，只需要声明“做什么”。

从技术实现上看，Python 装饰器是天然的“魔法贴纸”。@marvin.ai_classifier、@marvin.ai_extractor、@marvin.ai_fn 这些装饰器本质上是一个包装函数：它接收你编写的原始函数，读取函数名、docstring 和类型注解，再把这些信息连同输入参数一起构造成 prompt，发给大模型，最后把模型返回的文本转换成你声明的返回类型。

老张后来明白了：给菜谱卡贴贴纸，不是改菜谱本身，而是给菜谱配了一位“听得懂人话的大厨”。这也正是 Marvin 与普通函数调用最大的区别——贴纸没有改变“菜”，只是改变了“做菜的人”。

快速上手：五分钟贴出第一个智能菜谱

老张拆开魔法贴纸包装盒，发现盒子旁边有一张极简说明书。上面写着三步：第一步，把盒子里的工具准备好；第二步，在菜谱卡背面贴上贴纸；第三步，把菜谱卡递给顾客。整个过程不到五分钟，第一张“智能菜谱”就上岗了——顾客说“来碗不辣的牛肉面”，菜谱卡自己就明白要少放辣椒。

Marvin 的上手体验也如此轻快。先用 pip 安装：

然后配置 API 密钥。Marvin 的全局配置挂在 marvin.settings 对象上：

最后写一个带装饰器的函数，就完成了一个“AI 函数”：

这个函数体的代码永远不会被执行——真正干活的是装饰器背后的大模型。它会把函数签名、docstring 和传入的 dish 参数打包成一段 prompt，发给 LLM，再把返回的文本作为函数结果返回。

“第一个 AI 函数”背后的调用流程，可以浓缩成一个公式：

就这么简单。老张的第一个智能菜谱花了一盏茶的功夫就贴好了，而他那张原本“死板”的菜谱卡，从此成了店里最受顾客欢迎的“活菜谱”。

pip install marvin

import marvinmarvin.settings.openai.api_key = "sk-..."

import marvin @marvin.ai_fndef explain_dish(dish: str) -> str:    """用一句话介绍这道菜的特点和适合人群"""

智能分类：自动把顾客留言丢进对应抽屉

面馆生意红火后，顾客留言越来越多：“汤太咸了”“出餐速度慢”“牛肉很赞”。老张想把这些反馈按“好评”“差评”“其他”分门别类，方便月底复盘。如果靠人一张张看，费时又费力。他于是从贴纸盒里翻出一张贴着“分类”字样的魔法贴，往处理反馈的函数上一贴——留言自动飞进对应的抽屉里。

Marvin 里这张“分类贴纸”叫 @marvin.ai_classifier。用法如下：

神奇的地方在于：分类规则不需要你用 if/else 写，只需要在 docstring 里列出候选标签即可。Marvin 把函数名字、docstring、返回类型和输入文本一起构造成 prompt，让 LLM 自动判断该归到哪个标签。如果你想获得置信度，可以把返回类型标注为 tuple[str, float]，模型会额外输出一个 0 到 1 之间的置信度分数。

分类任务的本质，是让模型从有限个候选标签中选一个概率最大的。数学上可以写成：

回到面馆。老张只需要在 docstring 里说明分类标准，剩下的概率计算、排序、选最大，全是贴纸背后那位“AI 大厨”的心算。老张自己则泡了壶茶，看着留言一条条自动飞进抽屉。

import marvin @marvin.ai_classifierdef sentiment(text: str) -> str:    """返回 '好评', '差评' 或 '其他'"""

实体抽取：从一句话里“揪出”下单信息

面馆开通了微信点餐，顾客留言可随意了：“来2碗牛肉面，多放辣不要香菜”“一份凉菜，微辣谢谢”。老张发现，要把这些口语化的留言转换成结构化的订单表格（菜名、数量、备注），人工整理一个小时起步。他从贴纸盒里又翻出一张写着“抽取”的魔法贴——往转换函数上一贴，留言里的关键信息就像被无形的手抓住，自动填进表格。

\[\boxed{\text{这张贴纸是 } \ @marvin.ai\_extractor}\]

实体抽取的目标，是从非结构化文本中抽取出符合某种结构的信息。Marvin 的做法极具技巧：你用类型注解（尤其是 pydantic.BaseModel 子类）声明输出结构，装饰器就知道“要抽哪些字段”：

调用 parse_order("2碗牛肉面，多放辣不要香菜") 时，Marvin 会返回一个 Order(dish='牛肉面', quantity=2, note='多放辣不要香菜') 对象。字段类型为 int 的 quantity，Marvin 会确保 LLM 输出的是整数——这比单纯提示词抽取稳定得多。

抽取过程可以形象地写成：

老张看着系统后台自动生成的订单表格，感慨万千——以前要专门请人花半小时录入的留言，如今一句话的功夫就变成了一张干干净净的表格。这就是“抽取贴纸”的价值：让大模型当你的专属录入员。

import marvinfrom pydantic import BaseModel class Order(BaseModel):    dish: str    quantity: int    note: str = "" @marvin.ai_extractordef parse_order(text: str) -> Order:    """从点餐留言中抽取菜品、数量和备注"""

内容生成：会写文案的“AI 大厨”

老张的店面要上新品“藤椒鸡丝面”，需要一段诱人的菜单文案。老张自己写了两小时，憋出八个字“好吃不贵，欢迎品尝”。于是他把“生成”贴纸拿出来，往一个空函数上一贴，然后告诉函数：“帮我想想藤椒鸡丝面怎么宣传。”没过几秒，一段丰盈的文案就出现在屏幕上，从食材描述到口感层次，再到适合场景，一应俱全。

Marvin 中最通用的一张贴纸是 @marvin.ai_fn——它可以把任何输入输出描述清楚的函数变成 AI 能力。你不需要事先定义标签集合，也不需要设计结构化输出，只需要在 docstring 里写清楚“要做什么”，剩下的由模型自由发挥：

这里 docstring 就是“指令”本身：它描述了任务目标、风格约束、输出长度限制。Marvin 内部会把函数定义的描述性信息（函数名 + 参数名 + docstring）作为系统提示，把实际输入参数作为用户消息，一起发送给模型。整个过程是“上下文注入”的典型应用——你不必手工拼接 prompt，函数签名和 docstring 已经天然构成了 prompt。

生成任务的数学本质是从模型概率分布中采样：

老张把生成文案打印出来贴在菜单上，新菜品当晚就成了店里点击率最高的存在。“生成贴纸”解决了面馆最头疼的文案问题，而且每次生成都能保持统一风格——因为指令写在 docstring 里，就像后厨统一的调味配方。

import marvin @marvin.ai_fndef generate_menu_intro(dish: str) -> str:    """为菜品写一段 60 字以内、富有食欲的菜单介绍"""

参数调校：扭动魔法贴纸的“旋钮”

用过一阵子后，老张发现贴纸有时太“死板”：生成的好评回复千篇一律；有时又太“跳脱”：分类结果偶尔飘到不该去的抽屉。他想，要是魔法贴纸能像调节辣椒油一样调口味就好了。其实 Marvin 的每张贴纸都藏着一排“旋钮”——模型选择、温度参数、指令详细程度，三档搭配，味随意动。

第一颗旋钮是“模型选择”。Marvin 默认使用配置的 OpenAI 模型，但你可以全局设置，也可以在调用时临时覆盖：

第二个旋钮是“温度”（temperature）。温度控制生成结果的随机性：温度越低，输出越保守、确定性越高，适合分类和抽取（比如设为 0.1）；温度越高，输出越发散、越有创意，适合文案创作（比如设为 0.9）。Marvin 在请求级参数中可以灵活调节：

第三个旋钮是“指令优化”，往往最容易被忽略。docstring 写得越具体，输出质量越稳定。“写一句口号”和“写一句 15 字以内、包含‘藤椒’和‘椒麻’关键词、口语化的口号”，效果天差地别。

调参过程的模型可以概括为：

老张慢慢摸索出一套心得：处理订单留言、分类评价这种“不能飘”的活儿，就把温度调到最低；写宣传文案、设计新菜名这种“要出彩”的活儿，就把温度调高一些。贴纸没有变，但用的人懂了“旋钮”，出来的“菜”自然对味。

import marvinmarvin.settings.openai.model = "gpt-4o"

from marvin import ai_fn @ai_fndef generate_slogan(product: str) -> str:    """生成一句有创意的产品口号""" result = generate_slogan("藤椒鸡丝面", temperature=0.8)

对比 LangChain：街边“魔法贴”与五星酒店“宴会厅”

老张有一次去同行老李的餐厅参观，发现老李的后厨装了一整套“智能中央厨房系统”——能洗菜、能炒菜、能管理库存、还能指挥机器人上菜。但老李抱怨：这套系统光是培训员工就花了三个月，日常维护还常年养着一位技术专员。老张低头看看自己的魔法贴纸，笑了：我的厨房虽然小，但贴一张贴纸就能干活，剩下的功夫都在做菜上。

行业里的“中央厨房系统”就是 LangChain。LangChain 提供了链（Chain）、代理（Agent）、记忆（Memory）、向量库集成等完整框架，适合构建复杂的多步骤 AI 应用。而 Marvin 则是一个轻量库——有意思的是，Marvin 底层本身就依赖 LangChain，但它把复杂性全部封装了起来，对外只露出装饰器这一层极其简单的 API。

选框架的核心是“复杂度取舍”。LangChain 适合复杂的业务流程编排，例如“接收用户问题 → 检索知识库 → 调用工具 → 汇总回答”的多跳链路；Marvin 适合“把现有函数快速 AI 化”的轻量场景，例如把 classify()、extract()、generate() 这些单一职责的函数直接装饰成 AI 能力。如果你只是想在现有代码里给几个函数加上 AI 魔法，引入整套 LangChain 就像为了煎蛋买下整个宴会厅；而 Marvin 就是那枚只需一贴的煎蛋贴纸。

这种取舍可以用一个简单的“成本公式”表达：

老张明白了一个道理：工具没有绝对的好坏，只有是否匹配场景。他继续经营他的小面馆，用魔法贴纸过得滋润快活；老李的宴会厅虽然复杂，但也确实撑得起千人宴席。各得其所，才是架构选择的真谛。

调试与最佳实践：魔法失灵时的检查清单

一天，一位老顾客在留言里写“还是老样子”，结果系统分类成了“其他”，订单抽取也返回了空备注。老张第一次意识到：魔法贴纸不是万能的。他照着盒子背面的“故障排查指南”一步步检查，很快找到了问题的根源——原来 docstring 里没写清楚“老样子”是什么意思，导致 AI 大厨读不懂老主顾的“黑话”。

调试 Marvin 应用，第一站永远是日志。Marvin 基于 LangChain，而 LangChain 提供了详细的 prompt 日志——输出模型实际收到的完整提示词，就可以检查“贴纸上的字是否写清楚了”：

打开 DEBUG 日志后，你能看到每次调用生成的完整 prompt，以及模型的原始返回。如果分类结果不稳定，优先检查 docstring 是否包含足够明确的标签定义与判断标准；如果需要更精确的抽取，可以在 docstring 中加入字段示例（few-shot）或对 Pydantic 模型添加字段描述，让模型更容易理解字段语义。另外，输出格式偶发异常时，可用异常捕获加重试提升稳定性：

衡量一次调试是否成功，最终要靠“准确率”说话。你可以准备一组测试样本，计算模型输出的正确率：

老张后来在 docstring 里加了一句“如果顾客说‘老样子’，默认理解为上次点的菜品和口味”，系统立刻就变聪明了。调试的本质，就是不断把你脑海中默认的“潜规则”翻译成 AI 看得懂的明文指令。魔法贴纸没有失灵，它只是需要一个更细心的使用者。

import logginglogging.basicConfig(level=logging.DEBUG)

import marvin @marvin.ai_fndef get_dish(name: str) -> str:    """返回菜品的招牌介绍""" for _ in range(3):    try:        result = get_dish("藤椒鸡丝面")        break    except Exception:        continue

AI 应用场景

Python 演示

import marvinfrom pydantic import BaseModel  @marvin.ai_classifierdef sentiment(text: str) -> str:    """返回 '好评', '差评' 或 '其他'"""  class Order(BaseModel):    dish: str    quantity: int    note: str = ""  @marvin.ai_extractordef extract_order(text: str) -> Order:    """从点餐留言中抽取菜品名、数量和备注"""  @marvin.ai_fndef generate_slogan(dish: str) -> str:    """为菜品生成一句15字以内、有吸引力的宣传口号"""  if __name__ == "__main__":    feedback = "牛肉面很好吃，就是等太久了！"    print("分类结果:", sentiment(feedback))     msg = "来2碗牛肉面，多放辣不要香菜。"    order = extract_order(msg)    print("抽取结果:", order)     slogan = generate_slogan("藤椒鸡丝面")    print("生成口号:", slogan)

1. @marvin.ai_classifier把 sentiment 函数声明为一个 AI 分类器，docstring 里的“好评/差评/其他”就是分类标签。
2. class Order(BaseModel)定义抽取结果的结构，dish、quantity、note 三个字段告诉 LLM 需要从文本中提取哪些信息。
3. @marvin.ai_extractor让 extract_order 返回一个 Order 对象而不是字符串，Marvin 会自动校验并转换字段类型。
4. @marvin.ai_fn通用的 AI 函数装饰器，函数本身的 docstring 就是生成任务的指令。
5. if __name__ == "__main__":保证代码被直接运行时才执行演示逻辑，被 import 时不触发 AI 调用。

常见误区

面试题