marvin

Marvin：把 LLM 塞进 Python 类型系统的“环境智能”库

项目背景与痛点

LLM 落地时最尴尬的落差在于：开发者想要的是一个函数，拿到的却是一个聊天窗口。

主流 SDK 几乎都把模型包装成会话对象——你得亲手拼 system prompt、手工 json.loads、再写一堆 try/except 兜住模型偶尔吐出的脏数据。业务代码里于是长满了这种补丁：解析失败重试、字段缺失补默认值、类型对不上做映射。这些工作跟业务逻辑毫无关系，却是每个接入 LLM 的项目都要重复一遍的脏活。

Marvin 的切入点非常干脆：ambient intelligence——不造聊天机器人，把 LLM 降解成 Python 里一次普通的、带类型签名的函数调用。你写下 def sentiment(text: str) -> Literal["positive", "negative"]，剩下的 prompt 组装、结构化输出约束、结果反序列化、校验失败重试，全部由库接管。对调用方而言，它就是一个返回枚举值的同步（或异步）函数。

核心技术揭秘

Marvin 3.0 是一次彻底重写，底层改为构建在 Pydantic AI 之上。这个选择决定了它的全部技术性格：Pydantic 是整套设计的支点，而不是可选项。

签名即 Prompt。 @marvin.fn 装饰器在导入期就完成了一次“静态反射”：读取函数名、参数名、类型注解以及 docstring。docstring 的正文被当作指令主体，docstring 中的示例段落会被识别为 few-shot 样本，参数类型则成为输入侧约束。没有额外的 prompt 模板文件，没有 YAML 配置——函数定义本身就是唯一的真相来源。

类型即输出契约。 返回类型（Literal、Enum、BaseModel、list[...]、Optional[...]）经 Pydantic 转成 JSON Schema，作为结构化输出或工具 schema 交给模型；模型返回后走 model_validate_json，直接还原成 Python 对象。这一步是 Marvin 相比“让模型输出 JSON 然后自己 parse”的根本差异：约束由 schema 在生成侧施加，而不是在解析侧兜底。

校验闭环。 当输出不满足 schema——枚举越界、必填字段缺失、嵌套模型结构错位——Marvin 不会静默吞掉，而是把校验错误回填给模型触发重试，形成“生成 → 校验 → 反馈修正”的循环。重试次数是可配置的，这一点在生产环境里很关键，后文会展开。

运行时上下文。 模型配置、API key、默认客户端通过 contextvars 管理，调用方不必在每个函数调用处显式传参。“环境智能”这个词在这里落到了实处：配置一次，全局生效，且天然兼容 asyncio 的上下文隔离。

围绕这条主干，Marvin 还提供了几个语法糖变体：marvin.classifier 是面向一次性分类的专用化封装，marvin.model 用于快速声明轻量 schema，marvin.Application 则承载有状态的多轮交互。异步是原生的一等公民，批处理场景可以直接 asyncio.gather。

功能亮点与差异

放在同类坐标里看，Marvin 的位置相当清晰。

对比 LangChain / LlamaIndex：那套体系是“编排优先”，用 Chain、Runnable、LCEL 这些新抽象去描述流程，学习曲线陡，调试时要穿过好几层封装。Marvin 走的是零新增抽象路线——你不需要学任何新 DSL，只需要会写类型注解和 docstring。对于“我只是想把一段文本变成结构化数据”的场景，这个差异是量级的。

对比 Instructor / Outlines：它们同样解决结构化输出，但仍以“客户端调用”为圆心，你需要显式传入 response_model、自己管理消息列表。Marvin 把函数提升为一等公民，docstring 就是 prompt，调用形态更接近日常 Python。

另外两个容易被忽略的实用点：一是测试友好，库提供了 mock 机制，让 AI 函数在单测里可以被打桩，不必真的烧 token；二是强类型带来的 IDE 友好性，返回值有声明、能补全、能被 mypy 静态检查——这在 AI 相关库里并不常见。

应用场景与落地建议

适合：文本分类与打标、实体抽取、摘要、非结构化数据转 Pydantic 模型的 ETL 环节、大批量的异步批处理。凡是“输入一段文本，输出一个确定结构”的任务，Marvin 的表达力都绰绰有余。

不适合：复杂的多步 Agent 编排、长会话记忆管理、需要 token 级精细控制的推理链路。这类需求还是交给 LangGraph 或直接使用底层 SDK 更合适，硬套 Marvin 只会别扭。

生产落地有几条必须注意：

• docstring 即产品需求。 它不是注释，是 prompt。字段含义、边界情况、输出格式偏好都要写进去，最好配上正反例。
• 锁版本。 2.x 到 3.x 是一次不兼容重写（底层从直连各厂商 SDK 切到 Pydantic AI），beta/alpha 命名空间下的 API 仍在变动。上线前务必固定版本号。
• 控制重试成本。 结构化输出的校验重试意味着额外调用，要设上限，并在业务侧准备兜底默认值。
• 并发与缓存。 单次调用就是一次 LLM 请求，批处理必须异步 + 限流；输入可哈希的场景应该加结果缓存，能省下可观费用。
• 可观测性。 Pydantic AI 天然对接 OpenTelemetry / Logfire，尽早接入，否则线上排查 prompt 问题会非常痛苦。
• 敏感数据。 参数名与 docstring 都会进入 prompt，别把内部字段名、密钥、用户隐私塞进去。

综合评价

优点：抽象极薄，学习成本低到几乎为零；类型驱动的设计让工程化程度远高于同类；mock 测试机制和原生异步是实打实的加分项。

缺点：把 prompt 藏在 docstring 里有明显的“魔法感”，不熟悉这套约定的新人读代码会有一层理解成本；生态仍在快速演进，API 稳定性不足以让人放心追新；强绑定 Pydantic 世界观，团队若不接受这套类型体系，迁移会很痛；复杂 Agent 场景能力有限。

一句话总结：如果你认同“LLM 应该是一个有类型的函数，而不是一个聊天窗口”这个判断，Marvin 目前是 Python 生态里把这套理念执行得最干净的一个。它不试图成为平台，只试图从你的代码里消失——这恰恰是它最聪明的地方。