【免费下载链接】doc7Turn documents into AI-ready Markdown with visual understanding项目地址https://gitcode.com/gh_mirrors/do/doc7点击查看免费下载doc7 是一款把 PDF、Office、扫描件、截图、图表和公式转成 AI-ready Markdown 的文档转换工具。它的公开包github.com/magicrew/doc7与 CLI 共用同一套转换引擎你可以在自己的 Go 程序里通过Read、Convert、ConvertBatch三大 API 直接调用并用ProgressFunc回调实时跟踪每一页的转换进度。本文带你快速上手这三个入口的用法、选项默认值、进度事件与类型化错误处理。三大入口 API 总览先选对函数doc7 的三个公开入口对应三种输入场景选错函数是最常见的初学者错误API输入类型典型场景定义位置Read本地文件、目录、HTTP(S) URL、ZIP输入形态不确定时的统一入口api_read.goConvert单个本地文档或图片目录确定是单个本地文件api.goConvertBatch本地目录递归批量转换整个文件夹api.go简单记忆用户可能传给你的是文件、链接还是压缩包用Read它会在结果里告诉你最终是单文档document还是批量batch确定是单个本地文件用Convert返回最精简的Summary确定是一个文档目录用ConvertBatch返回逐文件明细BatchItem。一键上手用 Read 转换单个文档首先在项目里引入公开包不需要导入任何internal包go get github.com/magicrew/doc7一个最小可用的示例把本地 PDF 交给配置好的 OpenAI 兼容视觉模型package main import ( context log github.com/magicrew/doc7 ) func main() { options : doc7.DefaultReadOptions() options.OutputDir report-doc7 options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b result, err : doc7.Read(context.Background(), report.pdf, options) if err ! nil { log.Fatal(err) } if result.Document ! nil { log.Println(result.Document.MergedMarkdown) } }三个要点用doc7.DefaultReadOptions()起步只覆盖需要修改的字段其余保持与 CLIread命令一致的默认值见 api_read.goReadResult的Document和Batch两个指针字段互斥输入是单个文件时填Document输入是目录或 ZIP 时填Batch用result.Modedocument或batch判断result.Document.MergedMarkdown就是合并后的 Markdown 文件路径可直接喂给 RAG 入库。ReadOptions在基础选项之上多了一组批量与安全相关字段见 api_read.go字段含义FileWorkers批处理时并行处理的文件数ArchiveMaxFiles/ArchiveMaxBytesZIP 解压的文件数与体积上限防止恶意压缩包DownloadMaxBytes/DownloadTimeout远程 URL 下载的体积上限与超时Convert单文档转换与关键选项Convert接收一个本地路径和Options返回Summary定义见 api_types.go。Summary字段可以直接用于日志和可观测性字段说明MergedMarkdown/ManifestPath合并 Markdown 与 manifest 产物路径PagesTotal/PagesSuccess/PagesFailed页面总数与成功、失败页数PagesCached命中缓存的页数配合Resume断点续转GroundingWarnings文本层校验Text Grounding无法确认而保留首遍结果的页数Options中与日常开发最相关的字段模型接入Provider、BaseURL、Model、APIKey、Timeout页面控制Pages1 起始的闭区间页码如3-5、DPI渲染分辨率、Merge是否合并为单文件并发与重试Workers页面并发、RetryCount恢复与缓存Resume跳过已成功页只补失败页。DefaultOptions()的默认值与 CLI 完全一致见 api_defaults.gofunc main() { options : doc7.DefaultOptions() options.OutputDir report-doc7 options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b _, err : doc7.Convert(context.Background(), report.pdf, options) if err ! nil { panic(err) } }默认值一览PromptName: auto、Merge: true、Workers: 5、RetryCount: 3、DPI: 220、KeepImages: true、MaxTokens: 8192、ContextFallbacks: 2、MinImageDimension: 720、Timeout: 120s。其中 context fallback 是指模型因上下文不足拒绝请求时doc7 自动降低图片分辨率重试的机制最多重试ContextFallbacks次图片最长边最低降到MinImageDimension像素。ConvertBatch递归批量转换整个目录ConvertBatch递归转换inputDir下所有受支持的文档返回BatchSummary见 api_types.go字段说明FilesTotal/FilesDone/FilesFailed文件级统计DryRun为true时只扫描不转换适合先估价StartedAt/FinishedAt批次起止时间Items每个文档一条BatchItem含各自的Status、页面统计和Errorfunc main() { options : doc7.DefaultBatchOptions() options.OutputRoot out options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b options.FileWorkers 2 summary, err : doc7.ConvertBatch(context.Background(), inbox, options) if err ! nil { panic(err) } for _, item : range summary.Items { if item.Error ! nil { log.Printf(file %d failed: %s, item.Index, item.Error.Message) } } }批量场景的两个实用技巧先跑一次DryRun: true得到FilesTotal再按文件数决定FileWorkers批处理中断后用Resume: true重跑已成功的文档与页面会自动跳过。进度回调详解ProgressFunc 与 ProgressEvent三个入口都支持同一个进度回调类型ProgressFunc见 api_types.go把它赋值给Options.Progress或BatchOptions.Progress即可options.Progress func(event doc7.ProgressEvent) { switch event.Stage { case doc7.ProgressPageCompleted: fmt.Printf(page %d/%d %s\n, event.PagesCompleted, event.PagesTotal, event.Status) case doc7.ProgressFileCompleted: fmt.Printf(file %d/%d done\n, event.Index, event.Total) } }六种进度阶段阶段常量定义在 api_types.go阶段触发时机常用字段ProgressRenderStarted/ProgressRenderCompleted/ProgressRenderFailed文档渲染为页面图像的起止Input、OutputDir、ErrorProgressPageCompleted单页转换完成Page、PagesCompleted、PagesTotal、Cached、Duration、StatusProgressFileStarted/ProgressFileCompleted批处理中单个文件开始/结束Index、Total、PagesSuccess、PagesFailedProgressEvent的关键字段结构定义见 api_types.goPage/PagesTotal/PagesCompleted单页进度三件套做进度条用它们就够了SourcePagesTotal启用Pages页面选择时与选中页数区分的源文档总页数Cached该页是否命中缓存配合Resume续转时有用Duration该页或该文件的处理耗时Error *PageError非空表示失败Kind是稳定的机器可读错误分类Index/Total仅批处理文件事件有值。⚠️ 注意启用并发Workers 1时页面和文件事件可能并行到达回调内不要假设事件严格有序聚合计数请使用原子操作或加锁。回调的底层实现会把内部引擎的extract.ProgressEvent和batch.ProgressEvent适配为统一类型代码见 api_progress.go。类型化错误处理用 errors.As 精准重试转换失败时doc7 返回统一的*doc7.Error带稳定的错误分类和Retryable标志见 api_error.goErrorKind含义典型应对ConfigError配置缺失或非法检查 BaseURL/ModelAuthErrorAPI Key 无效检查凭据RateLimitError/TimeoutError/ServerError限流、超时、服务端错误Retryable为真指数退避重试RenderError本地渲染依赖失败缺 LibreOffice 等运行doc7 doctor检查PartialError部分页成功部分失败用Resume补转失败页result, err : doc7.Read(ctx, report.pdf, options) if err ! nil { var appErr *doc7.Error if errors.As(err, appErr) { switch appErr.Kind { case doc7.RateLimitError: // 退避后重试 case doc7.AuthError: // 提示用户检查 API Key } } }实践建议清单默认值起步始终从DefaultReadOptions()/DefaultOptions()/DefaultBatchOptions()派生只改必要字段避免漏配统一走 Read对外暴露的转换接口优先用Read让用户可以传文件、目录、URL 或 ZIP无需你写输入分发逻辑上下文取消把context.Context贯穿到底长任务可被上层优雅取消断点续转失败后开启Resume: true重跑同一OutputDir成功页走缓存只补失败页进度做 UIProgressEvent.PagesCompleted / PagesTotal驱动进度条Cached字段区分新转与命中缓存错误分类驱动重试只根据ErrorKind和Retryable做重试不要解析错误文案。相关资料公开 API 定义api.go、api_read.go、api_types.go、api_error.go默认值与 CLI 对齐api_defaults.go进度事件适配api_progress.go内部编排实现internal/read/read.go、internal/extract/extractor.go、internal/batch/batch.go中文 README 中的 Go 嵌入章节README.zh-CN.md转换质量基准测试benchmarks/visual-report/README.md赞分享【免费下载链接】doc7Turn documents into AI-ready Markdown with visual understanding项目地址https://gitcode.com/gh_mirrors/do/doc7点击查看免费下载相关推荐如何高效使用zTree_v3从API方法到回调函数的完全指南如何高效使用zTree_v3从API方法到回调函数的完全指南 zTree_v3是一款功能强大的jQuery树形插件它提供了丰富的API方法和灵活的回调函数前端UI库/组件Ultra-Pull-To-Refresh API完全参考接口参数与回调机制详解Ultra Pull To Refresh API完全参考接口参数与回调机制详解 Ultra Pull To Refresh是一款功能强大的Android下拉移动开发UI组件LlamaIndex Bedrock 嵌入集成详解BedrockEmbedding 类 API 参考与源码级实战LlamaIndex Bedrock 嵌入集成详解BedrockEmbedding 类 API 参考与源码级实战 本文基于 LlamaIndex 仓库中 do人工智能RAG大模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 17:38:12 · 阅读 1.2k 在Go里嵌入doc7：Read、Convert、ConvertBatch三大API参考与进度回调详解
【免费下载链接】doc7Turn documents into AI-ready Markdown with visual understanding项目地址https://gitcode.com/gh_mirrors/do/doc7点击查看免费下载doc7 是一款把 PDF、Office、扫描件、截图、图表和公式转成 AI-ready Markdown 的文档转换工具。它的公开包github.com/magicrew/doc7与 CLI 共用同一套转换引擎你可以在自己的 Go 程序里通过Read、Convert、ConvertBatch三大 API 直接调用并用ProgressFunc回调实时跟踪每一页的转换进度。本文带你快速上手这三个入口的用法、选项默认值、进度事件与类型化错误处理。三大入口 API 总览先选对函数doc7 的三个公开入口对应三种输入场景选错函数是最常见的初学者错误API输入类型典型场景定义位置Read本地文件、目录、HTTP(S) URL、ZIP输入形态不确定时的统一入口api_read.goConvert单个本地文档或图片目录确定是单个本地文件api.goConvertBatch本地目录递归批量转换整个文件夹api.go简单记忆用户可能传给你的是文件、链接还是压缩包用Read它会在结果里告诉你最终是单文档document还是批量batch确定是单个本地文件用Convert返回最精简的Summary确定是一个文档目录用ConvertBatch返回逐文件明细BatchItem。一键上手用 Read 转换单个文档首先在项目里引入公开包不需要导入任何internal包go get github.com/magicrew/doc7一个最小可用的示例把本地 PDF 交给配置好的 OpenAI 兼容视觉模型package main import ( context log github.com/magicrew/doc7 ) func main() { options : doc7.DefaultReadOptions() options.OutputDir report-doc7 options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b result, err : doc7.Read(context.Background(), report.pdf, options) if err ! nil { log.Fatal(err) } if result.Document ! nil { log.Println(result.Document.MergedMarkdown) } }三个要点用doc7.DefaultReadOptions()起步只覆盖需要修改的字段其余保持与 CLIread命令一致的默认值见 api_read.goReadResult的Document和Batch两个指针字段互斥输入是单个文件时填Document输入是目录或 ZIP 时填Batch用result.Modedocument或batch判断result.Document.MergedMarkdown就是合并后的 Markdown 文件路径可直接喂给 RAG 入库。ReadOptions在基础选项之上多了一组批量与安全相关字段见 api_read.go字段含义FileWorkers批处理时并行处理的文件数ArchiveMaxFiles/ArchiveMaxBytesZIP 解压的文件数与体积上限防止恶意压缩包DownloadMaxBytes/DownloadTimeout远程 URL 下载的体积上限与超时Convert单文档转换与关键选项Convert接收一个本地路径和Options返回Summary定义见 api_types.go。Summary字段可以直接用于日志和可观测性字段说明MergedMarkdown/ManifestPath合并 Markdown 与 manifest 产物路径PagesTotal/PagesSuccess/PagesFailed页面总数与成功、失败页数PagesCached命中缓存的页数配合Resume断点续转GroundingWarnings文本层校验Text Grounding无法确认而保留首遍结果的页数Options中与日常开发最相关的字段模型接入Provider、BaseURL、Model、APIKey、Timeout页面控制Pages1 起始的闭区间页码如3-5、DPI渲染分辨率、Merge是否合并为单文件并发与重试Workers页面并发、RetryCount恢复与缓存Resume跳过已成功页只补失败页。DefaultOptions()的默认值与 CLI 完全一致见 api_defaults.gofunc main() { options : doc7.DefaultOptions() options.OutputDir report-doc7 options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b _, err : doc7.Convert(context.Background(), report.pdf, options) if err ! nil { panic(err) } }默认值一览PromptName: auto、Merge: true、Workers: 5、RetryCount: 3、DPI: 220、KeepImages: true、MaxTokens: 8192、ContextFallbacks: 2、MinImageDimension: 720、Timeout: 120s。其中 context fallback 是指模型因上下文不足拒绝请求时doc7 自动降低图片分辨率重试的机制最多重试ContextFallbacks次图片最长边最低降到MinImageDimension像素。ConvertBatch递归批量转换整个目录ConvertBatch递归转换inputDir下所有受支持的文档返回BatchSummary见 api_types.go字段说明FilesTotal/FilesDone/FilesFailed文件级统计DryRun为true时只扫描不转换适合先估价StartedAt/FinishedAt批次起止时间Items每个文档一条BatchItem含各自的Status、页面统计和Errorfunc main() { options : doc7.DefaultBatchOptions() options.OutputRoot out options.BaseURL http://127.0.0.1:1234/v1 options.Model qwen3.5-4b options.FileWorkers 2 summary, err : doc7.ConvertBatch(context.Background(), inbox, options) if err ! nil { panic(err) } for _, item : range summary.Items { if item.Error ! nil { log.Printf(file %d failed: %s, item.Index, item.Error.Message) } } }批量场景的两个实用技巧先跑一次DryRun: true得到FilesTotal再按文件数决定FileWorkers批处理中断后用Resume: true重跑已成功的文档与页面会自动跳过。进度回调详解ProgressFunc 与 ProgressEvent三个入口都支持同一个进度回调类型ProgressFunc见 api_types.go把它赋值给Options.Progress或BatchOptions.Progress即可options.Progress func(event doc7.ProgressEvent) { switch event.Stage { case doc7.ProgressPageCompleted: fmt.Printf(page %d/%d %s\n, event.PagesCompleted, event.PagesTotal, event.Status) case doc7.ProgressFileCompleted: fmt.Printf(file %d/%d done\n, event.Index, event.Total) } }六种进度阶段阶段常量定义在 api_types.go阶段触发时机常用字段ProgressRenderStarted/ProgressRenderCompleted/ProgressRenderFailed文档渲染为页面图像的起止Input、OutputDir、ErrorProgressPageCompleted单页转换完成Page、PagesCompleted、PagesTotal、Cached、Duration、StatusProgressFileStarted/ProgressFileCompleted批处理中单个文件开始/结束Index、Total、PagesSuccess、PagesFailedProgressEvent的关键字段结构定义见 api_types.goPage/PagesTotal/PagesCompleted单页进度三件套做进度条用它们就够了SourcePagesTotal启用Pages页面选择时与选中页数区分的源文档总页数Cached该页是否命中缓存配合Resume续转时有用Duration该页或该文件的处理耗时Error *PageError非空表示失败Kind是稳定的机器可读错误分类Index/Total仅批处理文件事件有值。⚠️ 注意启用并发Workers 1时页面和文件事件可能并行到达回调内不要假设事件严格有序聚合计数请使用原子操作或加锁。回调的底层实现会把内部引擎的extract.ProgressEvent和batch.ProgressEvent适配为统一类型代码见 api_progress.go。类型化错误处理用 errors.As 精准重试转换失败时doc7 返回统一的*doc7.Error带稳定的错误分类和Retryable标志见 api_error.goErrorKind含义典型应对ConfigError配置缺失或非法检查 BaseURL/ModelAuthErrorAPI Key 无效检查凭据RateLimitError/TimeoutError/ServerError限流、超时、服务端错误Retryable为真指数退避重试RenderError本地渲染依赖失败缺 LibreOffice 等运行doc7 doctor检查PartialError部分页成功部分失败用Resume补转失败页result, err : doc7.Read(ctx, report.pdf, options) if err ! nil { var appErr *doc7.Error if errors.As(err, appErr) { switch appErr.Kind { case doc7.RateLimitError: // 退避后重试 case doc7.AuthError: // 提示用户检查 API Key } } }实践建议清单默认值起步始终从DefaultReadOptions()/DefaultOptions()/DefaultBatchOptions()派生只改必要字段避免漏配统一走 Read对外暴露的转换接口优先用Read让用户可以传文件、目录、URL 或 ZIP无需你写输入分发逻辑上下文取消把context.Context贯穿到底长任务可被上层优雅取消断点续转失败后开启Resume: true重跑同一OutputDir成功页走缓存只补失败页进度做 UIProgressEvent.PagesCompleted / PagesTotal驱动进度条Cached字段区分新转与命中缓存错误分类驱动重试只根据ErrorKind和Retryable做重试不要解析错误文案。相关资料公开 API 定义api.go、api_read.go、api_types.go、api_error.go默认值与 CLI 对齐api_defaults.go进度事件适配api_progress.go内部编排实现internal/read/read.go、internal/extract/extractor.go、internal/batch/batch.go中文 README 中的 Go 嵌入章节README.zh-CN.md转换质量基准测试benchmarks/visual-report/README.md赞分享【免费下载链接】doc7Turn documents into AI-ready Markdown with visual understanding项目地址https://gitcode.com/gh_mirrors/do/doc7点击查看免费下载相关推荐如何高效使用zTree_v3从API方法到回调函数的完全指南如何高效使用zTree_v3从API方法到回调函数的完全指南 zTree_v3是一款功能强大的jQuery树形插件它提供了丰富的API方法和灵活的回调函数前端UI库/组件Ultra-Pull-To-Refresh API完全参考接口参数与回调机制详解Ultra Pull To Refresh API完全参考接口参数与回调机制详解 Ultra Pull To Refresh是一款功能强大的Android下拉移动开发UI组件LlamaIndex Bedrock 嵌入集成详解BedrockEmbedding 类 API 参考与源码级实战LlamaIndex Bedrock 嵌入集成详解BedrockEmbedding 类 API 参考与源码级实战 本文基于 LlamaIndex 仓库中 do人工智能RAG大模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考