DeepSeek-OCR を uv 仮想環境でセットアップする方法
概要
uvを使って仮想環境を構築することで、失敗してもディレクトリごと削除すれば完全にリセットできます。 システムのPython環境を汚さずに、安全に実験できます。
セットアップ手順
1. プロジェクトディレクトリの作成
# プロジェクト用のディレクトリを作成
mkdir deepseek-ocr-project
cd deepseek-ocr-project
2. GitHubからリポジトリをクローン
# DeepSeek-OCR Dockerized APIをクローン
git clone https://github.com/Bogdanovich77/DeekSeek-OCR---Dockerized-API.git
cd DeekSeek-OCR---Dockerized-API
3. uvで仮想環境を作成
# 仮想環境を作成
uv venv
仮想環境の有効化
Linux/Mac の場合:
source .venv/bin/activate
Windows PowerShell の場合:
# 実行ポリシーエラーが出る場合は、まずこれを実行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
# 仮想環境を有効化
.venv\Scripts\Activate.ps1
Windows コマンドプロンプト (cmd) の場合:
.venv\Scripts\activate.bat
確認方法:
仮想環境が有効化されると、プロンプトの先頭に (.venv) が表示されます:
(.venv) PS C:\Users\yourname\deepseek-ocr-project\DeekSeek-OCR---Dockerized-API>
4. 必要なパッケージをインストール
基本パッケージのインストール
すべてのOS共通:
# PyTorch (CUDA 11.8版) をインストール
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
# 基本的な依存パッケージ
uv pip install fastapi uvicorn python-multipart
uv pip install pillow pdfplumber pdf2image
uv pip install pyyaml requests
# Hugging Face CLI(モデルダウンロード用)
uv pip install huggingface_hub
5. DeepSeek-OCR本体をクローン
Linux/Mac:
# DeepSeek-OCRの公式リポジトリをクローン
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
# DeepSeek-OCRディレクトリに移動して依存関係をインストール
cd DeepSeek-OCR
uv pip install -r requirements.txt
# flash-attnをインストール(オプショナル)
uv pip install flash-attn==2.7.3 --no-build-isolation
# プロジェクトルートに戻る
cd ..
Windows PowerShell:
# DeepSeek-OCRの公式リポジトリをクローン
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
# DeepSeek-OCRディレクトリに移動して依存関係をインストール
cd DeepSeek-OCR
uv pip install -r requirements.txt
# 注意: flash-attnはWindowsで問題が起きる可能性が高いです
# エラーが出た場合はスキップしても問題ありません(オプショナルな依存関係)
uv pip install flash-attn==2.7.3 --no-build-isolation
# プロジェクトルートに戻る
cd ..
ディレクトリ構造の確認:
DeekSeek-OCR---Dockerized-API/ ← プロジェクトルート
├── .venv/
├── DeepSeek-OCR/ ← ここに移動してrequirements.txtをインストール
│ ├── requirements.txt ← これを使う
│ ├── DeepSeek-OCR-master/
│ │ └── DeepSeek-OCR-vllm/
│ └── ...
├── models/
└── data/
6. モデルファイルのダウンロード
重要: モデルファイル(約6.6GB)は別の場所に保存することを推奨します。 そうすることで、プロジェクトディレクトリを削除してもモデルを再ダウンロードする必要がありません。
オプションA: プロジェクト内にダウンロード(シンプル)
# プロジェクト内にmodelsディレクトリを作成
mkdir -p models
# モデルをダウンロード
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir models/deepseek-ai/DeepSeek-OCR
オプションB: ホームディレクトリに保存(推奨)
Linux/Mac の場合:
# ホームディレクトリにモデル保存用ディレクトリを作成
mkdir -p ~/ai-models/deepseek-ocr
# モデルをダウンロード
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir ~/ai-models/deepseek-ocr
# プロジェクトからシンボリックリンクを作成
mkdir -p models/deepseek-ai
ln -s ~/ai-models/deepseek-ocr models/deepseek-ai/DeepSeek-OCR
Windows PowerShell の場合(管理者権限で実行):
- PowerShellを 管理者として実行 してから以下を実行:
# ホームディレクトリにモデル保存用ディレクトリを作成
New-Item -Path "$env:USERPROFILE\ai-models\deepseek-ocr" -ItemType Directory -Force
# モデルをダウンロード
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir "$env:USERPROFILE\ai-models\deepseek-ocr"
# プロジェクトディレクトリに戻って(通常のPowerShellで実行可能)
New-Item -Path "models\deepseek-ai" -ItemType Directory -Force
# シンボリックリンクを作成(管理者権限が必要)
New-Item -ItemType SymbolicLink -Path "models\deepseek-ai\DeepSeek-OCR" -Target "$env:USERPROFILE\ai-models\deepseek-ocr"
Windows コマンドプロンプト の場合(管理者権限で実行):
REM ホームディレクトリにモデル保存用ディレクトリを作成
mkdir %USERPROFILE%\ai-models\deepseek-ocr
REM モデルをダウンロード
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir %USERPROFILE%\ai-models\deepseek-ocr
REM プロジェクトディレクトリに戻って
mkdir models\deepseek-ai
REM シンボリックリンクを作成(管理者権限が必要)
mklink /D models\deepseek-ai\DeepSeek-OCR %USERPROFILE%\ai-models\deepseek-ocr
注意 (Windows):
- シンボリックリンクの作成には 管理者権限が必要 です
- 管理者権限なしで実行したい場合は、オプションAを使用してください
使い方
バッチ処理の実行
Linux/Mac:
# PDFファイルをdataディレクトリに配置
mkdir -p data
cp /path/to/your/document.pdf data/
# Markdown変換を実行
python pdf_to_markdown_processor_enhanced.py
# 結果を確認
ls data/*-MD.md
ls data/images/
Windows PowerShell:
# PDFファイルをdataディレクトリに配置
New-Item -Path "data" -ItemType Directory -Force
Copy-Item "C:\path\to\your\document.pdf" -Destination "data\"
# Markdown変換を実行
python pdf_to_markdown_processor_enhanced.py
# 結果を確認
Get-ChildItem data\*-MD.md
Get-ChildItem data\images\
APIサーバーの起動
Linux/Mac:
# FastAPIサーバーを起動
python start_server.py
# 別のターミナルでテスト
curl http://localhost:8000/health
Windows PowerShell:
# FastAPIサーバーを起動
python start_server.py
# 別のPowerShellウィンドウでテスト
Invoke-WebRequest -Uri http://localhost:8000/health | Select-Object -ExpandProperty Content
完全リセット方法
方法1: プロジェクトディレクトリごと削除(最もシンプル)
Linux/Mac の場合:
# 仮想環境を無効化
deactivate
# 親ディレクトリに移動
cd ..
# プロジェクトディレクトリごと削除
rm -rf deepseek-ocr-project
Windows PowerShell の場合:
# 仮想環境を無効化
deactivate
# 親ディレクトリに移動
cd ..
# プロジェクトディレクトリごと削除
Remove-Item -Recurse -Force deepseek-ocr-project
Windows コマンドプロンプト の場合:
REM 仮想環境を無効化
deactivate
REM 親ディレクトリに移動
cd ..
REM プロジェクトディレクトリごと削除
rmdir /s /q deepseek-ocr-project
注意: オプションAでモデルをダウンロードした場合、モデルファイルも削除されます(約6.6GB)。
方法2: 仮想環境のみリセット
Linux/Mac の場合:
# 仮想環境を無効化
deactivate
# 仮想環境ディレクトリを削除
rm -rf .venv
# 新しい仮想環境を作成して再スタート
uv venv
source .venv/bin/activate
# パッケージを再インストール
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
uv pip install fastapi uvicorn python-multipart pillow pdfplumber pdf2image pyyaml requests huggingface_hub
Windows PowerShell の場合:
# 仮想環境を無効化
deactivate
# 仮想環境ディレクトリを削除
Remove-Item -Recurse -Force .venv
# 新しい仮想環境を作成して再スタート
uv venv
.venv\Scripts\Activate.ps1
# パッケージを再インストール
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
uv pip install fastapi uvicorn python-multipart pillow pdfplumber pdf2image pyyaml requests huggingface_hub
ディレクトリ構成
オプションA使用時(プロジェクト内にモデル)
deepseek-ocr-project/
└── DeekSeek-OCR---Dockerized-API/
├── .venv/ # uv仮想環境(削除可能)
├── DeepSeek-OCR/ # 公式リポジトリ(削除可能)
│ ├── requirements.txt # ← これを使ってインストール
│ ├── DeepSeek-OCR-master/
│ │ └── DeepSeek-OCR-vllm/
│ └── ...
├── models/ # モデルファイル(削除すると再DL必要)
│ └── deepseek-ai/
│ └── DeepSeek-OCR/ # 約6.6GB
├── data/ # 入出力データ(削除可能)
├── pdf_to_markdown_processor.py
├── start_server.py
└── ...
完全削除: deepseek-ocr-project ディレクトリごと削除すればOK
オプションB使用時(モデルは別の場所)
~/ai-models/
└── deepseek-ocr/ # モデルファイル(保存)
└── [モデルファイル群]
deepseek-ocr-project/
└── DeekSeek-OCR---Dockerized-API/
├── .venv/ # uv仮想環境(削除可能)
├── DeepSeek-OCR/ # 公式リポジトリ(削除可能)
│ ├── requirements.txt # ← これを使ってインストール
│ ├── DeepSeek-OCR-master/
│ │ └── DeepSeek-OCR-vllm/
│ └── ...
├── models/ # シンボリックリンク(削除可能)
│ └── deepseek-ai/
│ └── DeepSeek-OCR/ -> ~/ai-models/deepseek-ocr
├── data/ # 入出力データ(削除可能)
└── ...
部分削除: deepseek-ocr-project ディレクトリのみ削除、モデルは保存
完全削除: deepseek-ocr-project と ~/ai-models/deepseek-ocr の両方を削除
トラブルシューティング
CUDA/PyTorchのバージョンエラー
Linux/Mac:
# CUDAバージョンを確認
nvidia-smi
# PyTorchのCUDA対応を確認
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'CUDA version: {torch.version.cuda}')"
Windows PowerShell:
# CUDAバージョンを確認
nvidia-smi
# PyTorchのCUDA対応を確認
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
python -c "import torch; print(f'CUDA version: {torch.version.cuda}')"
モデルが見つからないエラー
Linux/Mac:
# モデルパスを確認
ls -la models/deepseek-ai/DeepSeek-OCR/
# シンボリックリンクが正しいか確認
ls -la models/deepseek-ai/
Windows PowerShell:
# モデルパスを確認
Get-ChildItem -Path "models\deepseek-ai\DeepSeek-OCR\" -Force
# シンボリックリンクが正しいか確認
Get-ChildItem -Path "models\deepseek-ai\" -Force | Select-Object Name, Target
パッケージのインストールエラー
Linux/Mac:
# uvのキャッシュをクリア
uv cache clean
# 仮想環境を作り直す
deactivate
rm -rf .venv
uv venv
source .venv/bin/activate
Windows PowerShell:
# uvのキャッシュをクリア
uv cache clean
# 仮想環境を作り直す
deactivate
Remove-Item -Recurse -Force .venv
uv venv
.venv\Scripts\Activate.ps1
Windows での Visual C++ エラー
一部のパッケージ(特にflash-attn)のインストール時に Visual C++ ビルドツールが必要な場合があります:
- Microsoft C++ Build Tools をダウンロード
- インストーラーで「C++ によるデスクトップ開発」をチェック
- インストール後、PowerShellを再起動して再度パッケージをインストール
よくある質問
Q1: モデルを再ダウンロードしたくない場合は?
A: オプションBを使用してください。モデルをホームディレクトリに保存し、プロジェクトからシンボリックリンクで参照します。
Q2: 複数のプロジェクトで同じモデルを使いたい
A: オプションBが最適です。1つのモデルを複数のプロジェクトから参照できます。
Linux/Mac:
# プロジェクト1
cd ~/projects/project1
ln -s ~/ai-models/deepseek-ocr models/deepseek-ai/DeepSeek-OCR
# プロジェクト2
cd ~/projects/project2
ln -s ~/ai-models/deepseek-ocr models/deepseek-ai/DeepSeek-OCR
Windows PowerShell (管理者権限):
# プロジェクト1
cd C:\projects\project1
New-Item -ItemType SymbolicLink -Path "models\deepseek-ai\DeepSeek-OCR" -Target "$env:USERPROFILE\ai-models\deepseek-ocr"
# プロジェクト2
cd C:\projects\project2
New-Item -ItemType SymbolicLink -Path "models\deepseek-ai\DeepSeek-OCR" -Target "$env:USERPROFILE\ai-models\deepseek-ocr"
Q3: 仮想環境のサイズはどれくらい?
A: PyTorch + 依存パッケージで約5-7GB程度です(モデルファイルを除く)。
Q4: Dockerと比べてuvのメリットは?
A:
- メリット: 軽量、起動が速い、デバッグしやすい、Pythonコードの修正が即反映
- デメリット: 環境依存性あり、Dockerほど分離されていない
Q5: Windows で「実行ポリシー」エラーが出る
A: PowerShellの実行ポリシーを変更してください:
# 一時的に変更(現在のセッションのみ)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
# その後、仮想環境を有効化
.venv\Scripts\Activate.ps1
Q6: Windows でシンボリックリンクが作成できない
A: シンボリックリンクには管理者権限が必要です。以下の方法があります:
方法1: PowerShellを管理者として実行
- PowerShellを右クリック → 「管理者として実行」
- シンボリックリンク作成コマンドを実行
方法2: オプションAを使用(シンボリックリンク不要)
# プロジェクト内に直接ダウンロード
mkdir -p models
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir models/deepseek-ai/DeepSeek-OCR
Q7: Windows で uv コマンドが認識されない
A: uvをインストールしてPATHに追加してください:
# uvをインストール(PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
# PATHが通っていない場合は、PowerShellを再起動
クイックスタートスクリプト
全手順を自動化したスクリプトです。
Linux/Mac用
setup.sh として保存:
#!/bin/bash
set -e
echo "=== DeepSeek-OCR uv環境セットアップ ==="
# プロジェクトディレクトリ作成
mkdir -p deepseek-ocr-project
cd deepseek-ocr-project
# リポジトリクローン
git clone https://github.com/Bogdanovich77/DeekSeek-OCR---Dockerized-API.git
cd DeekSeek-OCR---Dockerized-API
# 仮想環境作成
echo "仮想環境を作成中..."
uv venv
source .venv/bin/activate
# PyTorchインストール
echo "PyTorchをインストール中..."
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
# 依存パッケージインストール
echo "依存パッケージをインストール中..."
uv pip install fastapi uvicorn python-multipart pillow pdfplumber pdf2image pyyaml requests huggingface_hub
# DeepSeek-OCRクローン
echo "DeepSeek-OCRをクローン中..."
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
cd DeepSeek-OCR
uv pip install -r requirements.txt
uv pip install flash-attn==2.7.3 --no-build-isolation
cd ..
# モデルディレクトリ作成
mkdir -p ~/ai-models
mkdir -p models/deepseek-ai
# モデルダウンロード(オプション)
read -p "モデルをダウンロードしますか? (約6.6GB) [y/N]: " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
echo "モデルをダウンロード中..."
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir ~/ai-models/deepseek-ocr
ln -s ~/ai-models/deepseek-ocr models/deepseek-ai/DeepSeek-OCR
echo "モデルのダウンロード完了"
fi
# dataディレクトリ作成
mkdir -p data
mkdir -p data/images
echo "=== セットアップ完了! ==="
echo ""
echo "使い方:"
echo " 1. 仮想環境を有効化: source .venv/bin/activate"
echo " 2. PDFファイルをdataディレクトリに配置"
echo " 3. 処理を実行: python pdf_to_markdown_processor_enhanced.py"
echo ""
echo "完全削除:"
echo " cd .. && rm -rf deepseek-ocr-project"
実行方法:
chmod +x setup.sh
./setup.sh
Windows PowerShell用
setup.ps1 として保存:
# エラーが発生したら停止
$ErrorActionPreference = "Stop"
Write-Host "=== DeepSeek-OCR uv環境セットアップ ===" -ForegroundColor Green
# プロジェクトディレクトリ作成
New-Item -Path "deepseek-ocr-project" -ItemType Directory -Force | Out-Null
Set-Location deepseek-ocr-project
# リポジトリクローン
Write-Host "リポジトリをクローン中..." -ForegroundColor Yellow
git clone https://github.com/Bogdanovich77/DeekSeek-OCR---Dockerized-API.git
Set-Location DeekSeek-OCR---Dockerized-API
# 仮想環境作成
Write-Host "仮想環境を作成中..." -ForegroundColor Yellow
uv venv
# 実行ポリシーを一時的に変更
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
# 仮想環境を有効化
& .venv\Scripts\Activate.ps1
# PyTorchインストール
Write-Host "PyTorchをインストール中..." -ForegroundColor Yellow
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
# 依存パッケージインストール
Write-Host "依存パッケージをインストール中..." -ForegroundColor Yellow
uv pip install fastapi uvicorn python-multipart pillow pdfplumber pdf2image pyyaml requests huggingface_hub
# DeepSeek-OCRクローン
Write-Host "DeepSeek-OCRをクローン中..." -ForegroundColor Yellow
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
Set-Location DeepSeek-OCR
uv pip install -r requirements.txt
uv pip install flash-attn==2.7.3 --no-build-isolation
Set-Location ..
# モデルディレクトリ作成
New-Item -Path "$env:USERPROFILE\ai-models" -ItemType Directory -Force | Out-Null
New-Item -Path "models\deepseek-ai" -ItemType Directory -Force | Out-Null
# モデルダウンロード(オプション)
$download = Read-Host "モデルをダウンロードしますか? (約6.6GB) [y/N]"
if ($download -eq "y" -or $download -eq "Y") {
Write-Host "モデルをダウンロード中..." -ForegroundColor Yellow
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir "$env:USERPROFILE\ai-models\deepseek-ocr"
# シンボリックリンク作成(管理者権限チェック)
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
if ($isAdmin) {
New-Item -ItemType SymbolicLink -Path "models\deepseek-ai\DeepSeek-OCR" -Target "$env:USERPROFILE\ai-models\deepseek-ocr" -Force | Out-Null
Write-Host "シンボリックリンクを作成しました" -ForegroundColor Green
} else {
Write-Host "警告: シンボリックリンクの作成には管理者権限が必要です" -ForegroundColor Red
Write-Host "オプション1: PowerShellを管理者として再実行してください" -ForegroundColor Yellow
Write-Host "オプション2: 以下のコマンドを手動で実行してください:" -ForegroundColor Yellow
Write-Host " New-Item -ItemType SymbolicLink -Path 'models\deepseek-ai\DeepSeek-OCR' -Target '$env:USERPROFILE\ai-models\deepseek-ocr'" -ForegroundColor Cyan
}
Write-Host "モデルのダウンロード完了" -ForegroundColor Green
}
# dataディレクトリ作成
New-Item -Path "data" -ItemType Directory -Force | Out-Null
New-Item -Path "data\images" -ItemType Directory -Force | Out-Null
Write-Host "`n=== セットアップ完了! ===" -ForegroundColor Green
Write-Host ""
Write-Host "使い方:" -ForegroundColor Cyan
Write-Host " 1. 仮想環境を有効化: .venv\Scripts\Activate.ps1"
Write-Host " 2. PDFファイルをdataディレクトリに配置"
Write-Host " 3. 処理を実行: python pdf_to_markdown_processor_enhanced.py"
Write-Host ""
Write-Host "完全削除:" -ForegroundColor Cyan
Write-Host " cd .. ; Remove-Item -Recurse -Force deepseek-ocr-project"
実行方法:
# 実行ポリシーを一時的に変更
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
# スクリプトを実行
.\setup.ps1
Windows ユーザー向けクイックスタート
最小限の手順(オプションA - プロジェクト内にモデル保存)
# 1. リポジトリをクローン
git clone https://github.com/Bogdanovich77/DeekSeek-OCR---Dockerized-API.git
cd DeekSeek-OCR---Dockerized-API
# 2. 仮想環境を作成・有効化
uv venv
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.venv\Scripts\Activate.ps1
# 3. PyTorchと依存パッケージをインストール
uv pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu118
uv pip install fastapi uvicorn python-multipart pillow pdfplumber pdf2image pyyaml requests huggingface_hub
# 4. DeepSeek-OCRをクローン
git clone https://github.com/deepseek-ai/DeepSeek-OCR.git
cd DeepSeek-OCR
uv pip install -r requirements.txt
# flash-attnはエラーが出てもスキップ可能
uv pip install flash-attn==2.7.3 --no-build-isolation
cd ..
# 5. モデルをダウンロード
New-Item -Path "models" -ItemType Directory -Force
huggingface-cli download deepseek-ai/DeepSeek-OCR --local-dir models/deepseek-ai/DeepSeek-OCR
# 6. PDFを処理
New-Item -Path "data" -ItemType Directory -Force
Copy-Item "your_document.pdf" -Destination "data\"
python pdf_to_markdown_processor_enhanced.py
完全削除方法(Windows)
# 仮想環境を無効化
deactivate
# 親ディレクトリに移動
cd ..
# プロジェクトを削除
Remove-Item -Recurse -Force DeekSeek-OCR---Dockerized-API
まとめ
✅ できること
- クリーンな環境構築: システムのPython環境を汚さない
- 簡単なリセット: ディレクトリごと削除すれば完全に削除可能
- 効率的なモデル管理: モデルを別の場所に保存して使い回し
- 高速な実験: Dockerより起動が速く、コード変更が即反映
🎯 推奨構成
- 学習・実験用: オプションB(モデル別保存)
- 一時的な使用: オプションA(プロジェクト内)
💡 重要なポイント
- モデルファイルは約6.6GBと大きいので、再ダウンロードを避けるために別の場所に保存することを推奨
- 仮想環境(.venv)は削除しても、
uv venvで簡単に再作成可能 - プロジェクトディレクトリごと削除すれば、完全にクリーンな状態に戻せる
作成日: 2025年10月24日 対象: DeepSeek-OCR Dockerized API + uv仮想環境 リポジトリ: https://github.com/Bogdanovich77/DeekSeek-OCR---Dockerized-API