スキップしてメイン コンテンツに移動

数式入りWordファイルをLLMに読ませる：eqword2llmの開発

研究者として日々の業務でWordファイルを扱う機会は多い。特に数式を含む技術文書をAIアシスタントに分析させたいとき、ある問題に直面した。

WordファイルをそのままLLMに渡しても、数式が正しく認識されない。

この課題を解決するために開発したのが eqword2llm だ。

課題：なぜ既存ツールでは不十分なのか

Pandocの限界

Pandocは優秀な変換ツールだが、Word特有の問題に対応しきれない。

たとえば、Wordの数式番号機能を使った文書を変換しようとする。




Pandocだと、以下のように変換される。

Equation with Field Code

$$\begin{array}{r}
\mathbf{E = m}\mathbf{c}^{\mathbf{2}}\mathbf{\#}\left( \mathbf{}\mathbf{\ SEQ\ Equation\ \backslash*\ ARABIC\ }\mathbf{}\mathbf{1}\mathbf{} \right)
\end{array}$$

Another Equation

$$\begin{array}{r}
\mathbf{F = ma\#}\left( \mathbf{}\mathbf{\ SEQ\ Equation\ \backslash*\ ARABIC\ }\mathbf{}\mathbf{2}\mathbf{} \right)
\end{array}$$

SEQ Equation というWordの内部フィールドコードがそのまま出力されてしまう。これではLLMが数式を正しく理解できない。

Mammothの限界

Mammothは数式を完全に無視する。見出し構造は保持されるが、肝心の数式が消えてしまっては科学技術文書には使えない。

eqword2llmの特徴

1. クリーンなLaTeX出力

同じ文書をeqword2llmで変換すると：

Equation with Field Code

$$
E=mc^{2}
$$

Another Equation

$$
F=ma
$$ 

フィールドコードは除去され、純粋なLaTeX数式のみが出力される。2. 標準的なLaTeX環境の使用

行列式の変換を比較してみる。

Pandoc:

$$|A| = \left| \begin{matrix}
a & b \\
c & d
\end{matrix} \right| = ad - bc$$

eqword2llm:

$$
\left|A\right|=\begin{vmatrix}a & b \\ c & d\end{vmatrix}=ad-bc
$$

eqword2llmは \begin{vmatrix} という標準的な行列式環境を使用する。コードが27%短くなり、意図も明確になる。

3. LLM-Ready出力形式（v0.4.0〜）

v0.4.0からは、LLMに渡すことを前提とした出力形式をサポートしている。

Structured Format（YAML Frontmatter付き）

eqword2llm document.docx --format structured

出力：

---
format: eqword2llm/v1
source: document.docx
stats:
  sections: 3
  equations: 5
  headings: 8
equations:
  - id: 1
    latex: "E = mc^{2}"
    type: block
  - id: 2
    latex: "F = ma"
    type: block
---

# 文書内容...

数式のリストと統計情報がメタデータとして付与される。LLMが文書構造を把握しやすくなる。

Prompt Format（LLMプロンプト生成）

eqword2llm document.docx --format prompt

変換結果をそのままLLM APIに渡せる形式で出力する：

# Document for Analysis

## Document Information
- Source: document.docx
- Equations: 5
- Sections: 3

## Content

[変換されたMarkdown]

---

## Instructions

This document was converted from a Word file using eqword2llm.
Mathematical equations are formatted in LaTeX:
- Block equations: `$$...$$`
- Inline equations: `$...$`

Please analyze the content. If you need clarification about any equation or
concept, ask the user.

使い方

インストール

pip install eqword2llm

依存パッケージはゼロ。Python標準ライブラリのみで動作する。

CLI

# 基本的な変換
eqword2llm paper.docx -o paper.md

# 数式番号なし
eqword2llm paper.docx -o paper.md --no-equation-numbers

# メタデータ付き
eqword2llm paper.docx -o paper.md --format structured

# LLMプロンプト形式
eqword2llm paper.docx --format prompt | pbcopy  # クリップボードにコピー

Python API

from eqword2llm import WordToMarkdownConverter

# 基本変換
converter = WordToMarkdownConverter("paper.docx")
markdown = converter.convert()

# メタデータ付き変換
result = converter.convert_structured()
print(f"数式数: {result.metadata.equation_count}")
for eq in result.metadata.equations:
    print(f"  [{eq.id}] {eq.latex}")

# LLMプロンプト生成
prompt = converter.to_llm_prompt()
# カスタム指示を追加
prompt = converter.to_llm_prompt(
    instructions="この文書の主要な方程式を解説してください。"
)

Claude APIとの連携

import anthropic
from eqword2llm import WordToMarkdownConverter

# Word文書をLLMプロンプトに変換
converter = WordToMarkdownConverter("research_paper.docx")
prompt = converter.to_llm_prompt()

# Claudeに送信
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    messages=[{"role": "user", "content": prompt}]
)

print(response.content[0].text)

変換の仕組み

Word文書（.docx）は実際にはZIPファイルで、内部にXMLが格納されている。数式はOMML（Office Math Markup Language）という形式で記述されている。

変換フロー

eqword2llmはこのOMMLを解析し、LaTeX形式に変換する。変換時に：

  1. Wordのフィールドコード（SEQ Equationなど）を除去
  2. 適切なLaTeX環境を選択（vmatrix, bmatrix, pmatrixなど）
  3. 数学関数を標準形式に変換（lim → \lim, sin → \sin）
  4. 見出し構造をMarkdown形式で保持

Pandocとの比較

機能Pandoceqword2llm
数式変換△ 部分的✅
フィールドコード処理❌✅
Markdown見出し❌✅
行列式環境\left|...\right|\begin{vmatrix}
ベクトル表記\overset{\rightarrow}{v}\vec{v}
メタデータ出力❌✅
LLMプロンプト生成❌✅
依存関係多数ゼロ

詳細な比較はcomparison-details.mdを参照。

今後の展望

現在検討している機能：

  • テーブル変換: Word表 → Markdownテーブル
  • 画像抽出: 埋め込み画像の外部ファイル化
  • クロスリファレンス: 数式参照の維持

まとめ

eqword2llmは「数式入りWord文書をLLMに正確に読ませる」という一点に集中したツールだ。

研究論文、技術レポート、講義資料など、数式を含む文書をAIアシスタントに分析させたいときに活用してほしい。

リポジトリ: https://github.com/manabelab/eqword2llm
 PyPI: https://pypi.org/project/eqword2llm/ 
ライセンス: MIT

Labels:

コメント

コメントを投稿

このブログの人気の投稿

Sourcetreeを使って、特定のブランチやタグをローカルに再現する方法 - フェッチ(fetch)を使おう -

今や、プログラミング開発に欠かせない存在となったGit。上司や同僚から「修正版をブランチ"devlop"にプッシュしたから、それを反映させてね」「安定版はタグ”v1.2”だから、よろしくね」と言われることもあるでしょう。その時に「どうやってブランチやタグって変えたらいいかわからない」「そもそも言われたブランチやタグが見当たらないんだけど…」となったら、とても困ってしまいます。そんなときにどうしたらいいか、本記事では Sourcetree を使用している環境を想定して、おすすめの手順を紹介します。環境によって具体的な操作は異なるものの、手順自体は一緒です。基本的には、 フェッチ(fetch)をしてリモートリポジトリをちゃんと確認 すればよいのです。 1. コミットしていないファイルをなくそう まず、Sourcetreeのコミット一覧に「コミットされていない変更があります」とあるかどうか確認します（下記図赤下線参照）。「コミット」の箇所に青マークでコミットされてないファイル数も表示されます（下記図赤枠参照）。その変更をコミットするか、破棄するかを行い、コミットされていない変更がない、きれいな状態にしましょう。そうしないと、後の作業中にエラー等が発生して進まなくなってしまいます。 2. フェッチしよう フェッチとは、 リモートリポジトリの最新の履歴の取得だけを行う 操作です。これによって、自分から見えていなかったブランチ・タグが見えるようになります。ブランチへのマージが伴うプッシュやプルと異なり、単に履歴を取得するだけなので、意図しないコミットが発生しません。安心して実施しましょう。Sourcetreeでは下記図赤枠部分をクリックすれば、フェッチを行うことができます。 その際出てくるポップアップで「すべてのリモートからフェッチ」「全てのタグを取得」をチェックしてください（下図赤下線参照）。 3. 目的のブランチ・タグを見つけよう 目的のブランチ・タグを見つけるのに便利なのが、Sourcetreeの左側領域にある「ブランチ」「タグ」「リモート」「スタッシュ」です。目的のブランチを探したい場合は「リモート」をクリックして現れる「origin」をさらにクリックしましょう。これでリモート上にあるブランチの一覧を見ることができます。タグの場合は「タグ」をクリック...
コメントを投稿
Read more »

SourcetreeでGitHubのプライベートリポジトリをクローンする

Sourcetree は、初心者でも操作しやすいgitのGUIツールです。基本無料のソフトなので、あらゆる人が導入・利用しやすいという利点を持ちます。ですが、GitHubで非公開、つまりプライベートのリポジトリを取り扱う場合には、初期設定に一工夫が必要です。 本記事で紹介する設定の流れは以下の通りです。前提として、1）GitHubのアカウントとプライベートリポジトリを既に所有しているが、2）Sourcetreeを自身のPCにまだインストールしていない状態を想定しています。 GitHubのPersonal access tokenを作成する Sourcetreeを自身のPCにインストールする SourcetreeにGitHubのアカウントを登録する プライベートリポジトリをクローンする 今回はPersonal access tokenという手法を用います。秘密鍵や公開鍵が必要なSSH接続とは異なり、アカウント名とパスワードのみで認証できます。そのため、アカウント管理がより重要となりますので、 2段階認証 でより強力なアカウント保護をおこなうことをお勧めします。また、本記事で紹介するのはWindowsでの利用です。Macでもほぼ同じ流れになるかと思いますが、試してはいませんのでご了承ください。 1. GitHubのPersonal access tokenを作成する GitHubのPersonal access tokenとは、GitHub API またはコマンドラインを使用するときに GitHub への認証でパスワードの代わりに使用できる機能です。このトークンを自身のGitHubアカウントで作成することで、Sourcetreeからプライベートリポジトリにアクセスすることができるようになります。具体的な作り方は下記のGitHub公式ページををご参考ください。 Personal access tokenの作成方法: https://docs.github.com/ja/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token ポイントは手順8に書かれているS ...
コメントを投稿
Read more »

GitHubのプライベートリポジトリからクローンできてもプッシュできないときの対処法　- Write権限の有無を確認しよう -

 以前、 SourceTreeを使って、GitHubのプライベートリポジトリにアクセスする方法 を記事にしました。その際、プライベートリポジトリからクローンできても、プッシュできない！という現象に遭遇するときがあります。下記のように、”そんなリポジトリは存在しないよ”というエラーが表示されます。 remote: Repository not found. もし、そのリポジトリがOrganaizationに属するものならば、 あなたのアカウントの権限が”Read”のみで、”Write”になっていない 可能性があります。権限に関してOrganaizationの管理者に確認してもらいましょう。 管理者がどういうルールで権限を決定しているのかによって、対応が変わるかと思います。一番手っ取り早い対応は、全てのメンバーのデフォルト権限を”Write”に変えてしまえばよいでしょう。Organaizationのページの右上にある「Settings」をクリックし、左に表示されるメニューから「Member privileges」を選択します。すると、左下のような画面が表示されますので、赤枠で囲っている「Base permissions」のプルダウン部分を"Write"に変更してください。 その他に、リポジトリ毎にアクセスできるメンバーを管理したい場合もあるかと思います。その際にはリポジトリの「Settings」→「Manage access」を選択し、設定等を変更してください。
コメントを投稿
Read more »