Attachments：两行代码让任意文件变身LLM上下文

Attachments是一个Python库，只需两行代码即可将PDF、Excel、Word、图片、音频等任意文件转换为LLM可理解的文本+图像格式，支持OCR、音频转录、智能分块等高级功能。

• 原作者/维护者：MaximeRivest
• 来源平台：github
• 原始标题：attachments
• 原始链接：https://github.com/MaximeRivest/attachments
• 来源发布时间/更新时间：2026-06-10T23:11:09Z

原作者与来源

• 原作者/维护者：MaximeRivest
• 来源平台：github
• 原始标题：attachments
• 原始链接：https://github.com/MaximeRivest/attachments
• 来源发布时间/更新时间：2026-06-10T23:11:09Z 原作者与来源\n\n- 原作者/维护者: Maxime Rivest\n- 来源平台: GitHub\n- 原始标题: attachments\n- 原始链接: https://github.com/MaximeRivest/attachments\n- 发布时间: 2026-06-10\n\n---\n\n项目概述\n\n在大语言模型（LLM）应用开发中，一个常见的痛点是如何将各种格式的文件内容注入到模型上下文中。无论是PDF报告、Excel表格、Word文档，还是图片、音频文件，开发者通常需要编写大量代码来解析、转换和格式化这些内容。\n\nAttachments 项目的诞生正是为了解决这一痛点。这个Python库的核心理念极其简洁：只需两行代码，就能将任意文件转换为LLM可以直接使用的文本+图像格式。它的目标是成为连接任意文件与大语言模型的通用漏斗。\n\n---\n\n核心设计理念\n\n极简API设计\n\nAttachments的设计哲学是"一个函数，一种输出格式，任意输入"。无论你处理的是PDF、Excel、图片还是音频文件，API调用方式完全一致：\n\npython\nfrom attachments import att\n\n处理PDF文件\nartifacts = att(\"report.pdf\")\n\n处理Excel表格\nartifacts = att(\"data.xlsx\")\n\n处理图片\nartifacts = att(\"image.png\")\n\n甚至整个目录\nartifacts = att(\"data/\")\n\n\n这种统一接口大大降低了学习成本，开发者不需要为每种文件格式学习不同的库和API。\n\n模块化依赖管理\n\n项目采用可选依赖的设计模式。核心库仅支持文本文件，其他格式按需安装：\n\n- pip install attachments[pdf] — PDF支持\n- pip install attachments[xlsx] — Excel支持\n- pip install attachments[docx] — Word支持\n- pip install attachments[image] — 图片支持\n- pip install attachments[ocr] — OCR扫描文档识别\n- pip install attachments[audio] — 音频转录\n\n这种设计避免了"依赖地狱"，用户只安装自己需要的功能。\n\n---\n\n高级功能特性\n\nDSL语法支持\n\nAttachments支持内联DSL语法，可以在文件路径后直接指定处理选项：\n\npython\n只处理PDF的前4页\nartifacts = att(\"report.pdf[pages: 1-4]\")\n\n指定分辨率和图片提取\nartifacts = att(\"report.pdf[pages: 1-10, images: true, dpi: 300]\")\n\nExcel指定工作表和行数\nartifacts = att(\"data.xlsx[sheet: Sales, rows: 100]\")\n\n强制OCR识别\nartifacts = att(\"scan.pdf[ocr: true]\")\n\n音频指定模型和语言\nartifacts = att(\"meeting.mp3[model: small, language: en]\")\n\n\n这种语法既直观又强大，避免了冗长的参数列表。\n\n结构化输出\n\n处理结果以统一的Artifacts对象返回，包含丰富的元数据：\n\npython\n{\n \"text\": \"提取的文本内容...\",\n \"images\": [], 图片项列表\n \"audio\": [], 预留字段\n \"video\": [], 预留字段\n \"meta\": {\n \"source\": \"report.pdf\",\n \"kind\": \"pdf\",\n \"segments\": [ 结构分段信息\n {\"kind\": \"page\", \"label\": \"page 1\", \"start\": 0, \"end\": 46},\n {\"kind\": \"page\", \"label\": \"page 2\", \"start\": 48, \"end\": 94}\n ],\n \"extra\": {\"encrypted\": False, \"pages\": 3}\n }\n}\n\n\n分段信息（segments）对于RAG（检索增强生成）应用特别有价值，可以精确定位内容来源。\n\n智能分块与RAG支持\n\nArtifacts对象内置了.chunk()方法，支持语义感知的分块：\n\npython\nartifacts = att(\"report.pdf\")\nchunks = artifacts.chunk(max_chars=4000) 按4000字符分块\n\n\n分块过程会尊重文档结构边界（如页面、段落），避免在句子中间截断。\n\n多模型直接集成\n\nArtifacts对象可以直接传递给主流LLM：\n\npython\nartifacts = att(\"report.pdf[images: true]\")\n\nClaude集成\nartifacts.claude(\"Summarize in one sentence.\")\n\nOpenAI集成\nartifacts.openai(\"Summarize in one sentence.\")\n\n\n系统会自动处理消息格式转换，包括图片的data URL编码。\n\n---\n\n服务回退模式\n\n当本地缺少某些依赖时，Attachments可以配置API回退模式：\n\npython\nfrom attachments import configure\nconfigure(api_key=\"att_...\")\nartifacts = att(\"document.pdf\") 如果本地没有pypdf，使用云服务\n\n\n这种混合模式兼顾了本地处理的隐私性和云服务的便利性。\n\n---\n\n开发者体验优化\n\nREPL友好设计\n\n在交互式环境中，Artifacts对象的repr显示简洁的摘要信息：\n\npython\n>>> att(\"report.pdf[pages: 1-2, images: true]\")\n<Artifacts: 1 artifact | 94 chars | ~24 tokens | 2 images>\n\n>>> att(\"missing.pdf\")\n<Artifacts: 1 artifact | 0 chars | ~0 tokens | 1 error>\n ! missing.pdf: unpack-error — unpack failed: Unsupported or non-existent input\n\n\n错误处理也很优雅，最多显示10条错误，其余折叠。\n\nJupyter Notebook支持\n\n在Jupyter环境中，直接显示Artifacts会渲染摘要、错误提示、文本预览和内联图片缩略图（最多4张），非常适合数据探索和调试。\n\n类型提示与自动补全\n\n项目包含完整的类型提示文件（init.pyi），编辑器可以提供准确的自动补全。att.options(\".pdf\")可以查看特定格式的可用选项。\n\n---\n\n实际应用场景\n\n1. 文档问答系统：将企业知识库文档统一转换为LLM上下文\n2. 多模态RAG应用：结合文本和图像信息进行检索增强\n3. 会议记录处理：音频转录+PDF附件一键处理\n4. 数据分析助手：Excel表格直接送入LLM进行分析\n5. 自动化报告生成：从多种数据源提取内容生成综合报告\n\n---\n\n项目前景与总结\n\nAttachments代表了LLM工具链的一个重要发展方向：降低文件处理的摩擦。随着多模态大模型的普及，能够统一处理文本、图像、音频等格式的工具将越来越重要。\n\n该项目的1.0版本是对0.25.x系列的完全重写，API更加成熟稳定。对于需要频繁处理各种文件格式的LLM应用开发者来说，Attachments值得密切关注和尝试。\n\n项目文档完善，包含迁移指南、愿景文档、开发指南等，社区友好度较高。