Word Document Extraction (WordExtractor)#

Overview#

WordExtractor in api/core/rag/extractor/word_extractor.py parses .docx files for Dify's RAG ingestion pipeline, producing a single Document with Markdown-formatted text that preserves images, hyperlinks, and tables. It is dispatched by ExtractProcessor for .docx files in both dify and unstructured ETL modes 1.

Key entry points:

Remote File Handling & SSRF Protection#

When file_path is a URL, __init__ downloads the file using remote_fetcher.make_request("GET", ...) and writes the response to a tempfile.NamedTemporaryFile. The temp file's path is then substituted as self.file_path for the rest of the extraction lifecycle.

Remote downloads previously used httpx.get directly. PR #31678 replaced this with remote_fetcher (which routes through ssrf_proxy) to prevent SSRF attacks 2.

⚠️ Windows PermissionError (Known Issue)#

On Windows, NamedTemporaryFile cannot be reopened while its file handle is still open. When python-docx opens self.file_path (the temp file), Windows raises PermissionError: [Errno 13] Permission denied. The workaround is delete=False + manual os.unlink() in close(), but this is not yet implemented — a # TODO comment marks the spot 3. Tracked as GitHub Issue #39889.

Image Extraction#

_extract_images_from_docx() iterates doc.part.rels and handles two cases:

• Embedded images (rel.is_external == False): reads rel.target_part.blob, saves to ext_storage under image_files/<tenant_id>/<uuid>.<ext>, creates an UploadFile record, and maps the part object → ![image](<FILES_URL>/files/<id>/file-preview) 4.
• External image URLs (rel.is_external == True): downloads via remote_fetcher, saves the same way, and maps r_id → the same preview URL 5.

The preview URL base is dify_config.FILES_URL 6. PR #35975 fixed a regression where INTERNAL_FILES_URL was used instead, making images unreachable from browsers 7.

UploadFile records are batched and committed after all images are processed; if _session is injected by the caller, the caller controls the commit 8.

Hyperlink Extraction#

Two hyperlink formats are handled inside parse_paragraph():

1. Modern w:hyperlink XML elements — process_hyperlink() reads r:id, resolves the relationship on doc.part.rels, and emits [text](url) for external relationships. Fixed in PR #30360 9.

2. Legacy HYPERLINK field codes (w:fldChar / w:instrText) — a state machine tracks begin / separate / end transitions 10, extracts the URL via regex from instrText, and captures the visible text from runs between separate and end.

Both formats are also handled inside table cells via _parse_cell_paragraph(). PR #33224 fixed cell-level parsing to support http and mailto links that were previously missed 11.

w:anchor internal bookmarks are intentionally left as plain text — only externally-referenced links with an r:id relationship are converted to Markdown 12.

Table Parsing & Pipe Escaping#

Tables are rendered as GitHub-Flavored Markdown by _table_to_markdown(), which calls _parse_row() → _parse_cell() → _parse_cell_paragraph(). Merged cells (column-span via cell.grid_span) are handled by filling spanned columns with empty strings 13.

Pipe character escaping: Cell content containing literal | characters (e.g., a | b) must be escaped to \| to preserve Markdown table structure. Without escaping, the pipe becomes an extra column separator, corrupting the table row. PR #41991 added this escaping in _parse_row 14.

Key Files#