Marvin AI工作流框架安装配置实战指南三分钟跑通第一个智能体应用【免费下载链接】marvinan ambient intelligence library项目地址: https://gitcode.com/gh_mirrors/ma/marvin如果你需要一个能写代码、查数据、分类文本还能把多个AI任务串成一条工作流的Python框架Marvin是一个相当省心的选择。它内置结构化输出、智能体Agent、任务编排和对话线程管理底层基于Pydantic AI引擎兼容OpenAI、Anthropic、Azure等多款模型。本文按先跑通、再深挖、最后调优的顺序带你亲手装好Marvin、配好密钥与模型再用两个真实场景把配置用起来。一、三分钟跑通最小配置安装这一步没有玄机Marvin是一个发布到PyPI的标准Python包依赖极少。你的电脑只要满足下面三个条件即可检查项要求Python 版本3.10 及以上推荐 3.11操作系统Windows 10 / macOS 10.15 / Linux 均可网络能访问你的大模型服务商接口推荐用uv这个现代包管理器它比pip更快、环境隔离更省心当然传统pip也完全支持# 方式一uv推荐 uv add marvin # 方式二pip pip install marvin如果你只是临时跑一个脚本甚至不需要先装进项目uv run --with marvin your_script.py一条命令即可带上Marvin执行。装好后配置一项最关键的密钥就可以开工了。Marvin默认使用OpenAI的模型把它写在环境变量里export OPENAI_API_KEY你的OpenAI密钥到这里最小配置已经完成。新建一个hello.py写下你的第一行AI代码import marvin # 最简单的调用一句话交给AI返回文字 print(marvin.run(写一首关于人工智能的俳句)) # 想要结构化结果指定 result_type 即可 answer marvin.run(宇宙的答案, result_typeint) print(answer) # 42运行python hello.py终端里会先打印出一条欢迎横幅然后给出AI生成的俳句和数字42。至此你的Marvin已经能干活了全程不超过三分钟。二、配置要素逐个击破跑通之后你会想控制它用哪个模型、把数据存在哪、日志打到多详细。Marvin把这一切统一成了一套环境变量 .env文件 运行时对象的三层配置体系理解起来很像调节一个音响开关、旋钮和预设各有分工。第一张卡片API密钥——你的入场券密钥是连接大模型服务商的凭证Marvin本身不存任何密钥只负责读取环境变量。最通用的做法是在终端里设置export OPENAI_API_KEYsk-...用Anthropic或Azure时同理换成各自的变量名即可。什么时候用任何一次调用之前都必不可少密钥配错是新手第一高频报错来源。第二张卡片模型选择——用provider:模型名一句话搞定Marvin默认模型是openai:gpt-4o。想换模型只需把格式为提供商:模型名的字符串填进来export MARVIN_AGENT_MODELopenai:gpt-4o-mini # 更便宜、更快 export MARVIN_AGENT_TEMPERATURE0.7 # 越高越有创造力 export MARVIN_AGENT_RETRIES5 # 结果无效时的重试次数温度temperature是调节创造力的旋钮写文案调到0.8左右处理财务数据降到0.2追求稳定输出就接近0。什么时候用想控制成本用迷你版模型想要高质量输出用旗舰模型。第三张卡片数据库——对话历史住哪儿Marvin会把线程、消息等历史数据存进数据库。默认使用SQLite位置在~/.marvin/marvin.db开箱即用、无需任何配置。想让数据落进自己的项目目录改一行export MARVIN_DATABASE_URLsqliteaiosqlite:///./my_app.db生产环境想上PostgreSQL同样一行切换export MARVIN_DATABASE_URLpostgresqlasyncpg://用户:密码localhost:5432/marvin什么时候用项目要共享、要备份、要并发访问时从SQLite升级到PostgreSQL。第四张卡片日志与输出——看得见才调得顺排查问题时把日志调到DEBUG能看到每一步模型调用和工具执行export MARVIN_LOG_LEVELDEBUG # 开发时 export MARVIN_LOG_LEVELWARNING # 生产时 export MARVIN_LOG_EVENTStrue # 额外记录全部事件 export MARVIN_ENABLE_DEFAULT_PRINT_HANDLERfalse # 关闭终端实时输出什么时候用开发阶段开DEBUG方便调试部署到线上把日志调高、关掉打印避免刷屏。第五张卡片用 .env 文件收拢全部配置项目越来越大时把变量写进项目根目录的.env文件Marvin启动时会自动加载比每次敲export省事得多# .env OPENAI_API_KEYsk-你的密钥 MARVIN_AGENT_MODELopenai:gpt-4o MARVIN_AGENT_TEMPERATURE0.7 MARVIN_LOG_LEVELINFO MARVIN_DATABASE_URLsqliteaiosqlite:///marvin_app.db提醒一句.env里躺着密钥务必把它加进.gitignore别让密钥跟着代码一起提交。配置总览表下面这张表汇总了最常用的全部配置项每个变量名、类型、默认值都与源码src/marvin/settings.py严格一致环境变量类型默认值作用MARVIN_HOME_PATHPath~/.marvinMarvin数据目录MARVIN_DATABASE_URLstrsqliteaiosqlite:/// home_path 下marvin.db数据库连接串MARVIN_LOG_LEVELstrINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICALMARVIN_LOG_EVENTSboolfalse是否把全部事件记为调试日志MARVIN_AGENT_MODELstropenai:gpt-4o默认Agent模型MARVIN_AGENT_TEMPERATUREfloatNone采样温度MARVIN_AGENT_RETRIESint10无效结果的自动重试次数MARVIN_MAX_AGENT_TURNSint100单次任务最大执行轮数MARVIN_ENABLE_DEFAULT_PRINT_HANDLERbooltrue是否开启终端实时输出MARVIN_MEMORY_PROVIDERstrchroma-ephemeral记忆提供商MARVIN_CHROMA_CLOUD_API_KEYstrNoneChroma云端密钥三、进阶玩法两个场景把配置用活光会写环境变量还不够配置要服务于真实需求。下面两个场景分别对应多模型切换和记忆持久化两类高频需求。场景一打造一个多模型客服机器人你希望客服机器人分类快、回复稳还想在不同模型之间做备份。第一步先配好两个服务商的密钥export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-...然后在代码里创建两个专职Agent一个负责理解意图、一个负责撰写回复并把它们编成一个Team协同工作import marvin from marvin import Agent classifier Agent( name意图分类员, modelopenai:gpt-4o-mini, instructions把用户问题分类为售前、售后、投诉、其他, ) responder Agent( name金牌客服, modelanthropic:claude-3-5-sonnet-latest, instructions语气友好、简洁、给出可执行的解决方案, ) with marvin.Thread() as thread: intent classifier.run(你们的货三天了还没到) reply responder.run( 针对以下意图生成回复, context{intent: intent} ) print(reply)这里的关键是模型可以用provider:模型名字符串直接指定也可以传入完整的Pydantic AI模型对象比如带自定义超时和代理的AnthropicModel。不同任务用不同模型就是Marvin里最常见的按需配置。场景二搭建带长期记忆的本地知识库问答默认的chroma-ephemeral是临时内存型向量数据库程序重启记忆就没了。想要跨会话记住用户偏好换成持久化方案export MARVIN_MEMORY_PROVIDERchroma-persistent export MARVIN_DATABASE_URLsqliteaiosqlite:///memory_app.dbMarvin会把对话要点写入向量库下次启动时自动检索回填配合Thread上下文管理器就能实现记得住前情的连续对话import marvin with marvin.Thread() as thread: marvin.run(记住用户偏好简洁的技术回答) # 下次会话继续 answer marvin.run(给我讲一下异步编程, context{style: 简洁})如果团队规模再大一些、需要向量检索能力更强还可以把MARVIN_MEMORY_PROVIDER切到qdrant或chroma-cloud云端版需要额外配置MARVIN_CHROMA_CLOUD_API_KEY、MARVIN_CHROMA_CLOUD_TENANT、MARVIN_CHROMA_CLOUD_DATABASE三个变量。用哪个完全取决于你的数据量和部署方式。四、避坑手册高频问题三段式排查按现象→原因→解法的方式把新手最容易踩的五个坑一次说清现象原因解法报错AuthenticationError或401密钥没设、设错或已过期重新export OPENAI_API_KEY并确认能访问模型服务商终端提示marvin: command not found安装成功但命令不在PATH中用pip install marvin后确认Python的bin目录在PATH里一直提示模型不存在MARVIN_AGENT_MODEL写错格式严格使用provider:model_name格式例如openai:gpt-4o日志信息太少查不到原因日志级别设成了INFO或更高开发时export MARVIN_LOG_LEVELDEBUG让每一步调用可见重启后记忆丢失用了默认的chroma-ephemeral内存库切到chroma-persistent或qdrant再补充三个容易忽略的检查点验证安装执行python -c import marvin; print(marvin.settings)能打印出全部配置即代表安装与加载正常。查看当前生效配置marvin.settings是运行时对象直接print(marvin.settings)即可看到所有变量真实值排查时第一件事就做这个。数据库状态自检命令行执行marvin db status可查看当前数据库URL与迁移版本确认连接串是否真的生效。如果你拿到了源码在做二次开发记得先按开发模式安装git clone https://gitcode.com/gh_mirrors/ma/marvin.git cd marvin uv venv source .venv/bin/activate uv sync --dev五、收尾行动指南到这里你其实已经掌握了Marvin安装→密钥→模型→存储→日志→进阶场景→排错的完整闭环。按下面的行动清单走一遍就能独立上手你的第一个AI工作流✅ 用pip install marvin或uv add marvin完成安装跑通hello.py✅ 配置OPENAI_API_KEY用marvin.run完成第一次调用✅ 建一个.env文件把模型、温度、数据库收拢在一起✅ 用AgentThread复现多模型客服或记忆问答场景✅ 遇到问题时先print(marvin.settings)再开DEBUG日志定位想深入理解每个配置项的源码实现可以翻看项目里的src/marvin/settings.py配置定义、src/marvin/defaults.py默认值管理和docs/guides/configuration.mdx配置说明文档。下一步建议你试着把marvin.run换成Task和Agent的组合写一个带工具调用的真实任务——那才是Marvin真正的威力所在。【免费下载链接】marvinan ambient intelligence library项目地址: https://gitcode.com/gh_mirrors/ma/marvin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Marvin AI工作流框架安装配置实战指南：三分钟跑通第一个智能体应用
Marvin AI工作流框架安装配置实战指南三分钟跑通第一个智能体应用【免费下载链接】marvinan ambient intelligence library项目地址: https://gitcode.com/gh_mirrors/ma/marvin如果你需要一个能写代码、查数据、分类文本还能把多个AI任务串成一条工作流的Python框架Marvin是一个相当省心的选择。它内置结构化输出、智能体Agent、任务编排和对话线程管理底层基于Pydantic AI引擎兼容OpenAI、Anthropic、Azure等多款模型。本文按先跑通、再深挖、最后调优的顺序带你亲手装好Marvin、配好密钥与模型再用两个真实场景把配置用起来。一、三分钟跑通最小配置安装这一步没有玄机Marvin是一个发布到PyPI的标准Python包依赖极少。你的电脑只要满足下面三个条件即可检查项要求Python 版本3.10 及以上推荐 3.11操作系统Windows 10 / macOS 10.15 / Linux 均可网络能访问你的大模型服务商接口推荐用uv这个现代包管理器它比pip更快、环境隔离更省心当然传统pip也完全支持# 方式一uv推荐 uv add marvin # 方式二pip pip install marvin如果你只是临时跑一个脚本甚至不需要先装进项目uv run --with marvin your_script.py一条命令即可带上Marvin执行。装好后配置一项最关键的密钥就可以开工了。Marvin默认使用OpenAI的模型把它写在环境变量里export OPENAI_API_KEY你的OpenAI密钥到这里最小配置已经完成。新建一个hello.py写下你的第一行AI代码import marvin # 最简单的调用一句话交给AI返回文字 print(marvin.run(写一首关于人工智能的俳句)) # 想要结构化结果指定 result_type 即可 answer marvin.run(宇宙的答案, result_typeint) print(answer) # 42运行python hello.py终端里会先打印出一条欢迎横幅然后给出AI生成的俳句和数字42。至此你的Marvin已经能干活了全程不超过三分钟。二、配置要素逐个击破跑通之后你会想控制它用哪个模型、把数据存在哪、日志打到多详细。Marvin把这一切统一成了一套环境变量 .env文件 运行时对象的三层配置体系理解起来很像调节一个音响开关、旋钮和预设各有分工。第一张卡片API密钥——你的入场券密钥是连接大模型服务商的凭证Marvin本身不存任何密钥只负责读取环境变量。最通用的做法是在终端里设置export OPENAI_API_KEYsk-...用Anthropic或Azure时同理换成各自的变量名即可。什么时候用任何一次调用之前都必不可少密钥配错是新手第一高频报错来源。第二张卡片模型选择——用provider:模型名一句话搞定Marvin默认模型是openai:gpt-4o。想换模型只需把格式为提供商:模型名的字符串填进来export MARVIN_AGENT_MODELopenai:gpt-4o-mini # 更便宜、更快 export MARVIN_AGENT_TEMPERATURE0.7 # 越高越有创造力 export MARVIN_AGENT_RETRIES5 # 结果无效时的重试次数温度temperature是调节创造力的旋钮写文案调到0.8左右处理财务数据降到0.2追求稳定输出就接近0。什么时候用想控制成本用迷你版模型想要高质量输出用旗舰模型。第三张卡片数据库——对话历史住哪儿Marvin会把线程、消息等历史数据存进数据库。默认使用SQLite位置在~/.marvin/marvin.db开箱即用、无需任何配置。想让数据落进自己的项目目录改一行export MARVIN_DATABASE_URLsqliteaiosqlite:///./my_app.db生产环境想上PostgreSQL同样一行切换export MARVIN_DATABASE_URLpostgresqlasyncpg://用户:密码localhost:5432/marvin什么时候用项目要共享、要备份、要并发访问时从SQLite升级到PostgreSQL。第四张卡片日志与输出——看得见才调得顺排查问题时把日志调到DEBUG能看到每一步模型调用和工具执行export MARVIN_LOG_LEVELDEBUG # 开发时 export MARVIN_LOG_LEVELWARNING # 生产时 export MARVIN_LOG_EVENTStrue # 额外记录全部事件 export MARVIN_ENABLE_DEFAULT_PRINT_HANDLERfalse # 关闭终端实时输出什么时候用开发阶段开DEBUG方便调试部署到线上把日志调高、关掉打印避免刷屏。第五张卡片用 .env 文件收拢全部配置项目越来越大时把变量写进项目根目录的.env文件Marvin启动时会自动加载比每次敲export省事得多# .env OPENAI_API_KEYsk-你的密钥 MARVIN_AGENT_MODELopenai:gpt-4o MARVIN_AGENT_TEMPERATURE0.7 MARVIN_LOG_LEVELINFO MARVIN_DATABASE_URLsqliteaiosqlite:///marvin_app.db提醒一句.env里躺着密钥务必把它加进.gitignore别让密钥跟着代码一起提交。配置总览表下面这张表汇总了最常用的全部配置项每个变量名、类型、默认值都与源码src/marvin/settings.py严格一致环境变量类型默认值作用MARVIN_HOME_PATHPath~/.marvinMarvin数据目录MARVIN_DATABASE_URLstrsqliteaiosqlite:/// home_path 下marvin.db数据库连接串MARVIN_LOG_LEVELstrINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICALMARVIN_LOG_EVENTSboolfalse是否把全部事件记为调试日志MARVIN_AGENT_MODELstropenai:gpt-4o默认Agent模型MARVIN_AGENT_TEMPERATUREfloatNone采样温度MARVIN_AGENT_RETRIESint10无效结果的自动重试次数MARVIN_MAX_AGENT_TURNSint100单次任务最大执行轮数MARVIN_ENABLE_DEFAULT_PRINT_HANDLERbooltrue是否开启终端实时输出MARVIN_MEMORY_PROVIDERstrchroma-ephemeral记忆提供商MARVIN_CHROMA_CLOUD_API_KEYstrNoneChroma云端密钥三、进阶玩法两个场景把配置用活光会写环境变量还不够配置要服务于真实需求。下面两个场景分别对应多模型切换和记忆持久化两类高频需求。场景一打造一个多模型客服机器人你希望客服机器人分类快、回复稳还想在不同模型之间做备份。第一步先配好两个服务商的密钥export OPENAI_API_KEYsk-... export ANTHROPIC_API_KEYsk-ant-...然后在代码里创建两个专职Agent一个负责理解意图、一个负责撰写回复并把它们编成一个Team协同工作import marvin from marvin import Agent classifier Agent( name意图分类员, modelopenai:gpt-4o-mini, instructions把用户问题分类为售前、售后、投诉、其他, ) responder Agent( name金牌客服, modelanthropic:claude-3-5-sonnet-latest, instructions语气友好、简洁、给出可执行的解决方案, ) with marvin.Thread() as thread: intent classifier.run(你们的货三天了还没到) reply responder.run( 针对以下意图生成回复, context{intent: intent} ) print(reply)这里的关键是模型可以用provider:模型名字符串直接指定也可以传入完整的Pydantic AI模型对象比如带自定义超时和代理的AnthropicModel。不同任务用不同模型就是Marvin里最常见的按需配置。场景二搭建带长期记忆的本地知识库问答默认的chroma-ephemeral是临时内存型向量数据库程序重启记忆就没了。想要跨会话记住用户偏好换成持久化方案export MARVIN_MEMORY_PROVIDERchroma-persistent export MARVIN_DATABASE_URLsqliteaiosqlite:///memory_app.dbMarvin会把对话要点写入向量库下次启动时自动检索回填配合Thread上下文管理器就能实现记得住前情的连续对话import marvin with marvin.Thread() as thread: marvin.run(记住用户偏好简洁的技术回答) # 下次会话继续 answer marvin.run(给我讲一下异步编程, context{style: 简洁})如果团队规模再大一些、需要向量检索能力更强还可以把MARVIN_MEMORY_PROVIDER切到qdrant或chroma-cloud云端版需要额外配置MARVIN_CHROMA_CLOUD_API_KEY、MARVIN_CHROMA_CLOUD_TENANT、MARVIN_CHROMA_CLOUD_DATABASE三个变量。用哪个完全取决于你的数据量和部署方式。四、避坑手册高频问题三段式排查按现象→原因→解法的方式把新手最容易踩的五个坑一次说清现象原因解法报错AuthenticationError或401密钥没设、设错或已过期重新export OPENAI_API_KEY并确认能访问模型服务商终端提示marvin: command not found安装成功但命令不在PATH中用pip install marvin后确认Python的bin目录在PATH里一直提示模型不存在MARVIN_AGENT_MODEL写错格式严格使用provider:model_name格式例如openai:gpt-4o日志信息太少查不到原因日志级别设成了INFO或更高开发时export MARVIN_LOG_LEVELDEBUG让每一步调用可见重启后记忆丢失用了默认的chroma-ephemeral内存库切到chroma-persistent或qdrant再补充三个容易忽略的检查点验证安装执行python -c import marvin; print(marvin.settings)能打印出全部配置即代表安装与加载正常。查看当前生效配置marvin.settings是运行时对象直接print(marvin.settings)即可看到所有变量真实值排查时第一件事就做这个。数据库状态自检命令行执行marvin db status可查看当前数据库URL与迁移版本确认连接串是否真的生效。如果你拿到了源码在做二次开发记得先按开发模式安装git clone https://gitcode.com/gh_mirrors/ma/marvin.git cd marvin uv venv source .venv/bin/activate uv sync --dev五、收尾行动指南到这里你其实已经掌握了Marvin安装→密钥→模型→存储→日志→进阶场景→排错的完整闭环。按下面的行动清单走一遍就能独立上手你的第一个AI工作流✅ 用pip install marvin或uv add marvin完成安装跑通hello.py✅ 配置OPENAI_API_KEY用marvin.run完成第一次调用✅ 建一个.env文件把模型、温度、数据库收拢在一起✅ 用AgentThread复现多模型客服或记忆问答场景✅ 遇到问题时先print(marvin.settings)再开DEBUG日志定位想深入理解每个配置项的源码实现可以翻看项目里的src/marvin/settings.py配置定义、src/marvin/defaults.py默认值管理和docs/guides/configuration.mdx配置说明文档。下一步建议你试着把marvin.run换成Task和Agent的组合写一个带工具调用的真实任务——那才是Marvin真正的威力所在。【免费下载链接】marvinan ambient intelligence library项目地址: https://gitcode.com/gh_mirrors/ma/marvin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考