乐于分享
好东西不私藏

我用 5 步搭了一个能读文档的 AI 助手

我用 5 步搭了一个能读文档的 AI 助手
不训练模型,也不用自己写算法。Python、DeepSeek API,再加几个文档解析库,就能做出一个会读 PDF、Word、TXT 的小助手。

我第一次认真研究 Agent 的时候,其实有点烦。
到处都是新词。Function Calling、RAG、多智能体、工作流、记忆、评估……每个词都像是一个入口,点进去又是十几个新概念。
后来我发现,入门 Agent 最好的办法,不是先啃框架文档。
先做一个小东西。
比如,一个能读文档的 AI 助手。
这个场景太常见了。你可能也遇到过。

领导发来一份 50 页 PDF,说半小时后要重点。

同事丢来几份合同,希望你把关键条款摘出来。

桌面上放着一堆 PDF、Word、TXT,格式乱,内容也长。

如果有个助手,你只要说一句,帮我读一下这份报告,总结主要内容。它能自己判断文件类型,调用对应工具,把内容提取出来,再交给大模型总结。
这篇文章就做这件事。
先不追求复杂系统。我们只搭一个最小可用版本。
能跑起来,比什么都重要。

这篇文章能帮你跑通什么

跟着做完,你大概能拿到这几块能力。
知道 Agent 和普通 Chatbot 差在哪
用 Python 读取 PDF、Word、TXT
把不同格式的文档转成 Markdown
用 @tool 把工具交给 AI
组装一个会自动选工具的文档处理 Agent
这个方案有两个现实优点。
第一,成本通常不高。
DeepSeek API 按量计费,普通文档总结的成本一般比较低,适合个人学习和轻量办公自动化。不过这里要补一句,DeepSeek 目前采用谷峰计价,高峰期,也就是常见上班时段,价格会更高。具体费用还是看官方计费页。
第二,安全上更可控。
文件解析在你本机完成,工具逻辑也在本地运行。原始 PDF、Word、TXT 文件一直留在你的电脑里,不会被直接上传到云端。真正发送给大模型的,是本地工具提取后的文本内容。
这和把整份文件直接丢给一个黑盒工具不太一样。你至少知道每一步发生了什么。
当然,敏感文档还是要小心。原始文件不直接上云,不代表提取后的文本就一定适合发给云端模型。合同、财务、客户信息、内部资料这些内容,最好先脱敏,或者直接走本地模型和权限控制。

01 先把 Agent 想简单一点

普通聊天 AI 更像一个只会回答问题的人。
你问它,这份报告讲了什么。
如果你没有把报告内容给它,它只能说,我看不到你的本地文件。
Agent 多了一步。
它可以使用工具。
一个很小的流程大概长这样。
用户,解析这份 PDFAI,判断任务,发现需要读取 PDFAI,调用 parse_pdf 工具工具,返回 PDF 文本AI,基于文本总结内容
这个过程就是 Function Calling,也就是函数调用。
你可以先粗暴地记成一句话。

Agent = 聊天 AI + 工具箱 + 选工具的能力。

普通 Chatbot 主要负责说。Agent 还要会判断该用哪个工具,并把工具跑起来。
本文的文档助手,就是一个很入门的 Agent。

02 先准备这些东西

别想太复杂,先把最小环境搭起来。
依赖可以先这样装。
pip install pypdf pdfplumber python-docx markitdown langchain langchain-openai
这里先别急着设计工程目录,也别一上来就搞 RAG。
先让它读到文件。

03 文档助手需要哪些工具

一个最小可用的文档助手,先处理三类文件就够了。
PDF → pypdf / pdfplumberWord → python-docxTXT → 直接读取多格式 → markitdown 统一转 Markdown
怎么选,可以先按这个来。
我自己的习惯是,先用确定性的工具把文档解析出来,再把文本交给大模型。
不要一开始就把所有事都丢给模型。
这样稳一点,出问题也好排查。

04 第一步,让 AI 能读 PDF

先从 PDF 开始。
最简单的方式是 pypdf。
from pypdf import PdfReaderreader = PdfReader(”你的文件.pdf”)print(f”共 {len(reader.pages)} 页”)print(reader.pages[0].extract_text())
这段代码能做两件事。
一是知道 PDF 有多少页。二是拿到第一页的文本。
如果 PDF 是中文,或者里面有表格,我更建议试试 pdfplumber。
import pdfplumberwith pdfplumber.open(”你的文件.pdf”) as pdf: text = pdf.pages[0].extract_text() tables = pdf.pages[0].extract_tables()
很多人第一次解析 PDF 会遇到一个问题,提取出来的文字换行很乱,空格很多,段落还会粘在一起。
这不是你写错了。
PDF 本身就不是按自然段落存储的。很多时候,它更像是一堆带坐标的文字块。
所以我们一般会加一点清洗逻辑。
import redef clean(text): text = re.sub(r'\n{3,}''\n\n', text) text = re.sub(r' {2,}'' ', text) return text.strip()
做到这里,助手已经能读 PDF 了。
别小看这一步。后面所有文档问答、合同提取、报告总结,都是从这里长出来的。

05 第二步,让 AI 能读 Word

企业里很多材料不是 PDF,而是 Word。
python-docx 的结构不难,大概是这三层。
Document 文档 ├── Paragraph 段落 │ └── Run 文字片段 └── Table 表格 └── Row 行 / Cell 单元格
读取段落很简单。
from docx import Documentdoc = Document(”你的文档.docx”)for p in doc.paragraphs: if p.text.strip(): print(f”[{p.style.name}] {p.text}”)
如果想把标题结构也保留下来,可以根据段落样式稍微处理一下。
parts = []for p in doc.paragraphs: if not p.text.strip(): continue if ”Heading” in (p.style.name or ””): parts.append(f”{p.text}”) else: parts.append(p.text)text = ”\n”.join(parts)
这样丢给大模型的时候,它看到的不是一坨文字,而是带一点层级的文本。
模型会舒服很多。
你也会舒服很多。

06 第三步,用 markitdown 做统一转换

如果你不想每种文件格式都写一套解析逻辑,可以试试微软开源的 markitdown。
它做的事很直接,把不同格式统一转成 Markdown。
from markitdown import MarkItDownmd = MarkItDown()text = md.convert(”报告.pdf”).text_contenttext = md.convert(”方案.docx”).text_contenttext = md.convert(”数据.xlsx”).text_content
为什么要转 Markdown?
因为标题、列表、表格这些结构能保留下来。大模型读 Markdown,一般也比读乱糟糟的纯文本更稳。
后面的流水线就清楚了。
不同格式文档 → Markdown → 分段 → 摘要 / 问答 / 提取字段
RAG、知识库、批量文档处理,基本都绕不开这一步。

07 第四步,把工具交给 AI

工具写好了,AI 还不知道自己能用哪些工具。
这时候要把工具注册给 Agent。
LangChain 里可以用 @tool。
from langchain_core.tools import tool@tooldef parse_pdf(file_path: str) -> str: ””” 解析 PDF 文件,提取文本内容。 适用场景,报告、合同、论文、规范文档等 PDF 文件。 输入,PDF 文件路径。 输出,PDF 的文本内容。 ”””解析逻辑 return result
这里最容易被忽略的是 docstring,也就是函数说明。
它不是普通注释。它是写给 AI 看的工具说明书。
一个好的 docstring,至少要讲清楚三件事。
工具做什么
什么情况下用
输入和输出是什么
如果你只写成这样。
def f1(path): ”””处理文件”””
模型很容易懵。
它不知道这个工具该不该用,也不知道什么时候用。
工具选错,很多时候不是模型笨,是你给它的说明太糊。

08 第五步,组装一个完整 Agent

现在可以把模型、工具和提示词拼起来了。
下面这段是一个最小可运行版本。
from langchain_openai import ChatOpenAIfrom langchain.agents import create_tool_calling_agent, AgentExecutorfrom langchain_core.prompts import ChatPromptTemplatefrom langchain_core.tools import toolfrom pypdf import PdfReaderfrom docx import Documentimport os@tooldef parse_pdf(file_path: str) -> str: ”””解析 PDF 文件。用户提到 PDF、报告、合同、论文时使用。””” reader = PdfReader(file_path) text = ”\n\n”.join( f”[第 {i+1} 页]\n{p.extract_text()}” for i, p in enumerate(reader.pages) if p.extract_text() ) return f”PDF 解析成功,共 {len(reader.pages)} 页。\n\n{text[:3000]}”@tooldef parse_docx(file_path: str) -> str: ”””解析 Word 文档。用户提到 Word、docx、方案、规范时使用。””” doc = Document(file_path) parts = [] for p in doc.paragraphs: if not p.text.strip(): continue if ”Heading” in (p.style.name or ””): parts.append(f”{p.text}”) else: parts.append(p.text) return ”DOCX 解析成功。\n\n” + ”\n”.join(parts[:3000])@tooldef parse_txt(file_path: str) -> str: ”””读取文本文件。用户提到 txt、md、log、纪要时使用。””” with open(file_path, encoding=”utf-8”) as f: text = f.read() return f”文本读取成功。\n\n{text[:3000]}”@tooldef list_files(directory: str = ”.”) -> str: ”””列出目录中的文件。用户想查看有哪些文件时使用。””” return ”\n”.join(sorted(os.listdir(directory)))TOOLS = [parse_pdf, parse_docx, parse_txt, list_files]llm = ChatOpenAI( model=”deepseek-chat”, base_url=”https://api.deepseek.com/v1”, api_key=”你的 API Key”, temperature=0,)prompt = ChatPromptTemplate.from_messages([ (”system”, ”””你是一个文档处理助手。根据用户输入和文件类型,自动选择合适的工具。如果文件路径明确,直接解析。如果路径不明确,先列出目录文件。”””), (”human”, ”{input}”), (”placeholder”, ”{agent_scratchpad}”),])agent = create_tool_calling_agent(llm, TOOLS, prompt)executor = AgentExecutor( agent=agent, tools=TOOLS, verbose=True, handle_parsing_errors=True, max_iterations=5,)result = executor.invoke({”input”: ”解析 test_docs/sample_report.pdf”})print(result[”output”])
跑起来之后,你可以这样用。
你,解析 report.pdfAI,自动选择 parse_pdf 工具,返回文档内容和总结你,帮我看看 spec.docx 里有什么AI,自动选择 parse_docx 工具,提取段落和结构你,当前目录有哪些文件AI,自动选择 list_files 工具,列出文件列表
这就是一个最小可用的文档 Agent。
它不花哨,但已经有了 Agent 最核心的能力。
根据任务,选工具,然后执行。

09 这只是第一阶段

如果你把上面的例子跑通了,Agent 学习里最重要的一道门槛,其实已经过了。
但它还很粗糙。
后面可以继续往下加能力。
阶段 1,工具使用让 AI 能读取 PDF、Word、TXT阶段 2,提示词链把解析、分段、摘要、提取字段串成流水线阶段 3,RAG 文档问答基于你的知识库回答问题,并给出引用来源阶段 4,并行化与路由同时处理多个文件,不同类型自动分发阶段 5,记忆与容错记住用户偏好,失败自动重试,关键节点人工确认阶段 6,多 Agent 协作检索、分析、写作、校对由不同 Agent 分工完成阶段 7,护栏与评估加入权限、安全、质量评测和企业级部署能力
这一篇只讲第一阶段,工具使用。
原因也简单。所有复杂 Agent,最后都要回到一个朴素问题。

它到底能调用哪些工具,这些工具靠不靠谱?


10 动手检查清单

你可以用下面这张清单检查一下,自己是不是真的跑通了。
能用 pypdf 获取 PDF 页数和文本
能用 pdfplumber 处理中文 PDF 和表格
能用 python-docx 读取 Word 段落和标题
能用 markitdown 把不同文件转成 Markdown
能写出清晰的 @tool 函数说明
能解释 Function Calling 的基本流程
能让 Agent 根据用户输入自动选择工具
能说明 Agent 和普通 Chatbot 的区别
能定位 Agent 选错工具的常见原因
都能做到的话,这一阶段就差不多了。
不需要装作很高深。
先跑通,就是进步。

11 几个容易踩坑的问题

Q1,PDF 提取出来是乱码怎么办?
先试 pdfplumber。如果还是乱码,可能是 PDF 使用了特殊字体,或者它本来就是扫描图片。前者要继续处理字体映射,后者需要 OCR。
Q2,扫描版 PDF 能处理吗?
本文这套代码不能直接处理。pypdf 和 pdfplumber 主要处理文字型 PDF。扫描版 PDF 要先走 OCR,比如 Tesseract、PaddleOCR。
Q3,Agent 为什么会选错工具?
最常见的原因是工具说明太模糊。尤其是 docstring 没写清楚使用场景、输入和输出,模型就容易猜错。
Q4,所有文档都适合发给云端模型吗?
不适合。合同、财务、客户信息、内部资料这些内容,先判断数据安全要求。该脱敏就脱敏,该本地模型就本地模型,不要图省事。

写在最后

这篇文章表面上是在讲怎么读 PDF、Word、TXT。
更底层一点,其实是在讲一个 Agent 思路。

先把任务拆成工具,再让 AI 学会选择工具。

当你把读文档做成工具,后面能扩展的事情就很多了。
总结报告、提取合同条款、生成会议纪要、批量整理知识库、自动生成 Word 文档。
这些都不是玄学。
就是一个工具一个工具往上接。
下一阶段,我会在这个文档助手的基础上继续往前推,把解析文档、分段、摘要、输出结构化结果串成一条自动化流水线。
如果你想拿这篇文章里的完整代码,可以在后台回复。

Agent学习

我会把本篇用到的代码脚本整理出来。

本文是「智能引力场」Agentic AI 系列的第一篇。后面会继续写 AI Agent、RAG、智能体工作流和自动化办公。