更新相关的文档和配置
This commit is contained in:
chenxin committed
1 parent
79db56a87b
commit
0d383725b5
6 files changed
+2459
-1949
No files matched your search
+95
-12
@@ -101,22 +101,42 @@ cd tianmu
|
||||
# 2. 创建虚拟环境并安装依赖
|
||||
uv venv -p 3.12
|
||||
source .venv/bin/activate
|
||||
uv sync --extra rapidocr
|
||||
|
||||
# 3. 启动天目（推荐）
|
||||
# 3. 安装依赖（根据平台和需求选择）
|
||||
# macOS（Apple Silicon）推荐
|
||||
uv sync --system-certs --extra macos
|
||||
|
||||
# Linux/Windows（带 GPU 支持）
|
||||
uv sync --extra all
|
||||
|
||||
# 仅 PP-OCRv6（所有平台）
|
||||
uv sync --system-certs --extra rapidocr
|
||||
|
||||
# 4. 启动天目（推荐）
|
||||
uv run tianmu
|
||||
|
||||
# 4. 验证健康检查
|
||||
# 5. 验证健康检查
|
||||
curl http://localhost:8101/healthz
|
||||
|
||||
# 5. 测试 OCR（base64 图片）
|
||||
# 6. 测试 OCR（base64 图片）
|
||||
python3 tests/test_ocr.py
|
||||
```
|
||||
|
||||
## 平台与依赖说明
|
||||
|
||||
| 平台 | 推荐命令 | 说明 |
|
||||
| ------ | --------- | ------ |
|
||||
| **macOS（Apple Silicon）** | `uv sync --system-certs --extra macos` | 自动使用 CPU/MPS，跳过 GPU 依赖 |
|
||||
| **Linux（NVIDIA GPU）** | `uv sync --extra all` | 自动使用 CUDA 12.8 版本 |
|
||||
| **Windows（NVIDIA GPU）** | `uv sync --extra all` | 自动使用 CUDA 12.8 版本 |
|
||||
| **所有平台（仅 CPU）** | `uv sync --system-certs --extra rapidocr --extra vl` | 通用 CPU 版本 |
|
||||
|
||||
> **注意**：macOS 用户需要使用 `--system-certs` 标志来解决 SSL 证书验证问题，或在 `~/.zshrc` 中设置 `export UV_SYSTEM_CERTS=true`。
|
||||
|
||||
## 启动方式对比
|
||||
|
||||
| 命令 | 适用场景 | reload | 泄漏警告 |
|
||||
|------|---------|--------|---------|
|
||||
| ------ | --------- | -------- | --------- |
|
||||
| `uv run tianmu` | 开发（推荐） | ❌ | ❌ |
|
||||
| `uv run uvicorn src.main:app --port 8101 --reload` | 开发热重载 | ✅ | ⚠️ reloader 进程可能打印 resource_tracker 警告 |
|
||||
| `python3 -m src.main` | 快速测试 | ❌ | ❌ |
|
||||
@@ -125,7 +145,7 @@ python3 tests/test_ocr.py
|
||||
|
||||
## 启动和测试
|
||||
|
||||
天目提供两种测试方式：
|
||||
天目提供三种测试方式：
|
||||
|
||||
### 方式一：远程图片测试
|
||||
|
||||
@@ -225,17 +245,53 @@ docker compose -f docker/docker-compose.app.yml --profile tianmu up -d --build h
|
||||
|
||||
## 依赖分组
|
||||
|
||||
天目提供灵活的依赖安装方式，适应不同平台和场景：
|
||||
|
||||
### 基础分组
|
||||
|
||||
| Extra | 包含内容 | 适用平台 |
|
||||
| ------- | --------- | --------- |
|
||||
| `rapidocr` | PP-OCRv6 引擎（CPU） | 所有平台 |
|
||||
| `rapidocr-gpu` | PP-OCRv6 引擎（GPU） | Linux/Windows 仅 |
|
||||
| `vl` | PaddleOCR-VL 引擎 | 所有平台（GPU 自动适配） |
|
||||
| `dev` | 开发工具（pytest, ruff, pre-commit） | 所有平台 |
|
||||
| `lint` | 代码检查（black, mypy, ruff） | 所有平台 |
|
||||
| `test` | 测试工具（pytest 系列） | 所有平台 |
|
||||
|
||||
### 组合分组
|
||||
|
||||
| Extra | 包含内容 | 适用平台 | 安装命令 |
|
||||
| ------- | --------- | --------- | --------- |
|
||||
| `all` | rapidocr + vl + GPU（非 macOS） | 所有平台（自动适配） | `uv sync --extra all` |
|
||||
| `macos` | rapidocr + vl + dev + lint + test | macOS 专用 | `uv sync --system-certs --extra macos` |
|
||||
| `gpu` | rapidocr-gpu + vl | Linux/Windows 专用 | `uv sync --extra gpu` |
|
||||
| `dev-all` | dev + lint + test | 所有平台 | `uv sync --extra dev-all` |
|
||||
|
||||
### 安装示例
|
||||
|
||||
```bash
|
||||
# 仅 PP-OCRv6（默认推荐）
|
||||
uv sync --extra rapidocr
|
||||
# macOS 开发环境（推荐）
|
||||
uv sync --system-certs --extra macos
|
||||
|
||||
# PP-OCRv6 + PaddleOCR-VL（需要复杂文档解析）
|
||||
uv sync --extra rapidocr --extra vl
|
||||
|
||||
# 所有可选
|
||||
# Linux/Windows 生产环境（GPU）
|
||||
uv sync --extra all
|
||||
|
||||
# 所有平台通用 CPU 版本（仅运行环境）
|
||||
uv sync --system-certs --extra rapidocr --extra vl
|
||||
|
||||
# 仅 PP-OCRv6（轻量部署）
|
||||
uv sync --system-certs --extra rapidocr
|
||||
|
||||
# 仅开发工具
|
||||
uv sync --system-certs --extra dev-all
|
||||
```
|
||||
|
||||
> **跨平台自动适配**：
|
||||
>
|
||||
> - **PyTorch**：在 Linux/Windows 上自动使用 CUDA 12.8 版本，在 macOS 上使用 CPU/MPS 版本
|
||||
> - **ONNX Runtime**：在 macOS 上自动使用 CPU 版本，在 Linux/Windows 上可使用 GPU 版本
|
||||
> - **SSL 证书**：macOS 用户需要 `--system-certs` 或设置 `UV_SYSTEM_CERTS=true`
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
@@ -245,3 +301,30 @@ pytest tests/ -v
|
||||
# 集成测试（需先启动服务）
|
||||
python3 tests/test_ocr.py
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: macOS 上安装时出现 SSL 证书错误？
|
||||
|
||||
```bash
|
||||
# 使用系统证书
|
||||
uv sync --system-certs
|
||||
|
||||
# 或设置环境变量（永久解决）
|
||||
export UV_SYSTEM_CERTS=true
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Q: macOS 上 `onnxruntime-gpu` 安装失败？
|
||||
|
||||
天目已自动处理此问题。在 macOS 上使用 `--extra macos` 或 `--extra all` 时会自动跳过 GPU 依赖。如遇到问题，请确保使用最新的 `pyproject.toml` 配置。
|
||||
|
||||
### Q: 如何确认 PyTorch 使用了正确的后端？
|
||||
|
||||
```bash
|
||||
# macOS 检查 MPS 支持
|
||||
python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'MPS available: {torch.backends.mps.is_available()}')"
|
||||
|
||||
# Linux 检查 CUDA 支持
|
||||
python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"
|
||||
```
|
||||
Reference in new issue
Block a user