Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

[Bug]: Same PDF gives different markdown on each run when batch_size > 1 (threads share current_page_number)

クローズ 初心者向け
  • 何か問題がありますか？
#2,319 コメント 4 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 2 日以内に返信

@Kylinny がすでに取り組んでいます。

2026年9月30日 から。

  • #2320 @Kylinny による — オープン

評価

難易度
2/5
見積もり時間
1〜3時間
初心者へのやさしさ
84/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
python
領域
backend

調査の方向性

processors/pdf/processor.py の NaivePDFProcessorStrategy.process_batch()、_process_page()、_extract_images() から始め、共有されている current_page_number がどのように使用されているかを確認します。batch_size=4 と batch_size=1 で repro.py を実行し、繰り返し実行しても決定的であること、1 ページ目のフォーマットが 1 ページ目に維持されること、ページ番号と画像名が正しいことを確認します。

索引モデルが issue の本文から書いたものです。

説明

⚙ Done 🐞 Bug 🥸 - Medium
crawl4ai version

0.9.0 (also reproduced with processors/pdf/processor.py and utils.py from v0.9.4; the code involved is unchanged on main)

Expected Behavior

This report was drafted with the help of an AI assistant. The reproduction below was run locally.

Processing the same PDF twice should give the same markdown, and the page-1-only formatting in clean_pdf_text() should only ever apply to page 1.

Current Behavior

With the default batch_size=4 (also the default of PDFContentScrapingStrategy), the output changes from run to run for the same file. In the repro below, a Title Case line that clean_pdf_text() treats as an author line (which it only does on page 1) ends up bolded on page 1, on no page at all, or on other pages, giving 5 to 7 distinct outputs over 30 runs. With batch_size=1 the output is always the same. We noticed because we hash the extracted text to detect changed documents, and unchanged PDFs looked changed on every crawl.

The cause is in NaivePDFProcessorStrategy.process_batch(). Each worker writes its page number to the shared processor instance, and _process_page() reads it back after text extraction, by which time another worker may have overwritten it:

def process_page_safely(page_num: int):
    ...
    self.current_page_number = page_num + 1
    return self._process_page(page, image_dir)

# _process_page()
pdf_page.markdown = clean_pdf_text(self.current_page_number, pdf_page.raw_text)
pdf_page.html = clean_pdf_text_to_html(self.current_page_number, pdf_page.raw_text)

The same attribute also feeds PDFPage.page_number and the extracted image file names (page_{current_page_number}_img_{n}).

Suggested fix: pass the page number down instead of storing it on self, i.e. self._process_page(page, image_dir, page_num + 1), and use that argument in _process_page() and _extract_images(). With that change the repro gives a single output for batch_size=4 as well.

Workaround: PDFContentScrapingStrategy(batch_size=1).

Is this reproducible?

Yes

Inputs Causing the Bug
- URL(s): none, the script below generates a local 12-page PDF
- Settings used: NaivePDFProcessorStrategy(batch_size=4), the default, vs batch_size=1
- Input data: each page has a Title Case line that clean_pdf_text() only bolds on page 1
Steps to Reproduce
1. pip install "crawl4ai[pdf]" fpdf2
2. Save the code snippet below as repro.py
3. python repro.py
4. Compare the batch_size=4 and batch_size=1 results
Code snippets
# pip install "crawl4ai[pdf]" fpdf2
from collections import Counter
from pathlib import Path

from fpdf import FPDF

from crawl4ai.processors.pdf.processor import NaivePDFProcessorStrategy

# 12 pages, each with a Title Case line that clean_pdf_text() only bolds on page 1.
path = Path("race.pdf")
pdf = FPDF()
pdf.set_font("Helvetica", size=12)
for n in range(1, 13):
    pdf.add_page()
    pdf.cell(0, 10, f"Chapter Heading Number {n}", new_x="LMARGIN", new_y="NEXT")
    pdf.cell(0, 10, "Assessment Overview", new_x="LMARGIN", new_y="NEXT")
    pdf.multi_cell(0, 8, f"this is the body of page {n}. " * 60)
pdf.output(str(path))

for batch_size in (4, 1):
    outputs = Counter()
    for _ in range(30):
        result = NaivePDFProcessorStrategy(batch_size=batch_size).process_batch(path)
        bolded = tuple(
            number
            for number, page in enumerate(result.pages, start=1)
            if "**Assessment Overview**" in page.markdown
        )
        outputs[bolded] += 1
    print(f"batch_size={batch_size}: {len(outputs)} distinct outputs over 30 runs")
    for bolded, runs in outputs.most_common():
        print(f"  {runs:2d} runs: bolded on pages {list(bolded)}")
OS

Linux (Arch Linux)

Python version

3.12.12

Browser

No response

Browser version

No response

Error logs & Screenshots (if applicable)

Output of repro.py on 0.9.0:

batch_size=4: 7 distinct outputs over 30 runs
  18 runs: bolded on pages [1]
   7 runs: bolded on pages []
   1 runs: bolded on pages [4]
   1 runs: bolded on pages [5]
   1 runs: bolded on pages [1, 3]
   1 runs: bolded on pages [1, 2]
   1 runs: bolded on pages [2]
batch_size=1: 1 distinct outputs over 30 runs
  30 runs: bolded on pages [1]
主要言語
Python
スター
85.9k
フォーク
8.9k
平均マージ
5日 8時間
マージ済み PR（30日）
24

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

unclecode/crawl4ai のほかの issue

unclecode/crawl4ai の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。