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

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

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-10T23:11:09.000Z
- 最近活动: 2026-06-10T23:21:40.481Z
- 热度: 114.8
- 关键词: Python, LLM, 文件处理, PDF, OCR, RAG, 多模态, Attachments
- 页面链接: https://www.zingnex.cn/forum/thread/attachments-llm-94d7f7f6
- Canonical: https://www.zingnex.cn/forum/thread/attachments-llm-94d7f7f6
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：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\n**Attachments** 项目的诞生正是为了解决这一痛点。这个Python库的核心理念极其简洁：只需两行代码，就能将任意文件转换为LLM可以直接使用的文本+图像格式。它的目标是成为连接任意文件与大语言模型的通用漏斗。\n\n---\n\n## 核心设计理念\n\n### 极简API设计\n\nAttachments的设计哲学是"一个函数，一种输出格式，任意输入"。无论你处理的是PDF、Excel、图片还是音频文件，API调用方式完全一致：\n\n```python\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\n### DSL语法支持\n\nAttachments支持内联DSL语法，可以在文件路径后直接指定处理选项：\n\n```python\n# 只处理PDF的前4页\nartifacts = att(\"report.pdf[pages: 1-4]\")\n\n# 指定分辨率和图片提取\nartifacts = att(\"report.pdf[pages: 1-10, images: true, dpi: 300]\")\n\n# Excel指定工作表和行数\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\n```python\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\n```python\nartifacts = att(\"report.pdf\")\nchunks = artifacts.chunk(max_chars=4000)  # 按4000字符分块\n```\n\n分块过程会尊重文档结构边界（如页面、段落），避免在句子中间截断。\n\n### 多模型直接集成\n\nArtifacts对象可以直接传递给主流LLM：\n\n```python\nartifacts = att(\"report.pdf[images: true]\")\n\n# Claude集成\nartifacts.claude(\"Summarize in one sentence.\")\n\n# OpenAI集成\nartifacts.openai(\"Summarize in one sentence.\")\n```\n\n系统会自动处理消息格式转换，包括图片的data URL编码。\n\n---\n\n## 服务回退模式\n\n当本地缺少某些依赖时，Attachments可以配置API回退模式：\n\n```python\nfrom attachments import configure\nconfigure(api_key=\"att_...\")\nartifacts = att(\"document.pdf\")  # 如果本地没有pypdf，使用云服务\n```\n\n这种混合模式兼顾了本地处理的隐私性和云服务的便利性。\n\n---\n\n## 开发者体验优化\n\n### REPL友好设计\n\n在交互式环境中，Artifacts对象的repr显示简洁的摘要信息：\n\n```python\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\n### Jupyter 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项目文档完善，包含迁移指南、愿景文档、开发指南等，社区友好度较高。