Metadata-Version: 2.4
Name: transwarp-cosmic
Version: 1.2.5
Summary: Document parsing with OCR, layout analysis, and table and formula recognition
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: openvino
Requires-Dist: openvino==2026.2.1; extra == "openvino"
Provides-Extra: tensorrt
Requires-Dist: tensorrt-cu12==10.9.0.34; extra == "tensorrt"
Requires-Dist: tbb==2021.13.1; extra == "tensorrt"
Requires-Dist: nvidia-cuda-runtime-cu12==12.9.37; sys_platform == "win32" and extra == "tensorrt"
Requires-Dist: nvidia-cuda-runtime==13.0.96; sys_platform == "linux" and extra == "tensorrt"

# Cosmic 文档解析与音频转写

Cosmic 可解析 PDF、图片、Word、PowerPoint 和 Excel 文件，支持版面分析、OCR、表格和公式识别。也支持转写音频文件和视频中的音轨，导出文本和字幕。

## 运行环境

适用于 Windows 11 和 Ubuntu 24.04 LTS（x86-64），需要 Python 3.10 或更新版本。Windows 需要 Microsoft Visual C++ x64 运行库。使用 CPU 推理时无需 GPU 或 NPU 驱动。

| 设备 | Windows 11 驱动参考 | Ubuntu 24.04 LTS 驱动参考 |
| --- | --- | --- |
| NVIDIA GPU（TensorRT） | `576.02` 或更新版本，对应 [CUDA 12.9](https://docs.nvidia.com/cuda/archive/12.9.0/cuda-toolkit-release-notes/index.html) | `580.95.05` 或更新版本，对应 [CUDA 13.0 Update 2](https://docs.nvidia.com/cuda/archive/13.0.2/cuda-toolkit-release-notes/index.html) |
| Intel GPU（OpenVINO） | Intel Arc Graphics `32.0.101.9175` | [Intel Graphics Compute Runtime `26.27.39122.11`](https://github.com/intel/compute-runtime/releases/tag/26.27.39122.11) |
| Intel NPU（OpenVINO） | Intel AI Boost `32.0.100.5540` | [Intel Linux NPU Driver `1.33.0`](https://github.com/intel/linux-npu-driver/releases/tag/v1.33.0) |

Intel 驱动版本随硬件型号而异。Ubuntu 上请按厂商说明为设备选择匹配的内核与驱动。

## 安装

按设备选择推理后端。

- CPU 或 Intel GPU/NPU 使用 `python -m pip install "transwarp-cosmic[openvino]"`。
- NVIDIA GPU 使用 `python -m pip install "transwarp-cosmic[tensorrt]"`。
- 两种后端都需要时，使用 `python -m pip install "transwarp-cosmic[openvino,tensorrt]"`。

## 使用

### 解析文档

解析 PDF 后，打开 `output` 目录中 ZIP 压缩包内的 `content.md` 查看结果。

```cmd
cosmic --backend openvino -i "input.pdf" -o "output"
```

### 启动服务

启动 HTTP 服务后，可在浏览器中上传文档。 [打开本地服务](http://127.0.0.1:5000/)

```cmd
cosmic-server --backend openvino --host 127.0.0.1 --port 5000
```

使用 TensorRT 时，将上述命令中的 `--backend openvino` 改为 `--backend tensorrt`。仅用 CPU 运行 OpenVINO 时，将 `COSMIC_OV_LAYOUT_DEVICE`、`COSMIC_OV_OCRDET_DEVICE` 和 `COSMIC_OV_OCRREC_DEVICE` 都设为 `CPU`。

### 转写音频

支持 MP3、WAV、FLAC、M4A、OGG 等音频文件，也可转写 MP4 等视频中的音轨。先在服务网页上选择语种并下载语音模型。已有本地语音模型时，也可以用 `--asr-model-path` 指定对应语种的模型目录。

```cmd
cosmic -i "meeting.mp3" -o "output" --asr-locale zh-CN
```

也可在服务网页上传音频。结果 ZIP 包含 `content.md`、带时间戳的 `transcript.json` 以及 `content.srt` 和 `content.vtt` 字幕。

## 命令行参数

### `cosmic` 和 `cosmic-server` 通用参数

| 参数 | 说明 |
| --- | --- |
| `--backend` | 指定 `openvino`、`tensorrt`、`qnn` 或 `cann`。默认按此顺序选择第一个可加载的后端。QNN 和 CANN 需要额外的后端库，可用 `COSMIC_MODEL_LIBRARY_PATH` 指定其目录。 |
| `--mode` | 文档解析模式。默认 `pipeline`，也可选 `hybrid` 或 `vlm`。 |
| `--ocr-model` | OCR 模型。可选 `PP-OCRv6_tiny`、`PP-OCRv6_small`（默认）或 `PP-OCRv6_medium`。 |
| `--vlm_config` | VLM 请求配置的 JSON 文件路径。选择 `hybrid` 或 `vlm` 时必填。 |
| `-b` / `--batch-size` | PDF 内部处理批大小。`cosmic` 默认 `2`，`cosmic-server` 默认 `4`。 |
| `-h` / `--help` | 显示帮助并退出。 |

### `cosmic` 参数

| 参数 | 说明 |
| --- | --- |
| `-i` / `--input` | 输入文件路径，必填。 |
| `-o` / `--output` | 结果目录，默认 `./tmp`。 |
| `-s` / `--start`、`-e` / `--end` | PDF 起止页，从 `0` 开始编号，包含两端。默认从首页到末页。 |
| `--info` | 显示文件标识和 PDF 所选范围的页数，或报告输入为媒体文件，然后退出。 |
| `--asr-locale` | 语音模型语种，例如 `zh-CN` 或 `en-US`。 |
| `--asr-model-path` | 本地语音模型目录，需同时指定 `--asr-locale`。启用说话人区分时，该目录需包含 `diarization.onnx`。 |
| `--asr-diarization` | 启用说话人区分，默认关闭。 |
| `--asr-workers` | 音频转写并行度，默认 `1`。 |
| `-v` / `--version` | 显示版本并退出。 |

### `cosmic-server` 参数

| 参数 | 说明 |
| --- | --- |
| `--host` | 监听地址，默认 `127.0.0.1`。允许其他机器访问时设为 `0.0.0.0`。 |
| `--port` | HTTP 端口，默认 `5000`。 |
| `-w` / `--workers` | PDF 渲染进程数，默认 `4`。 |
| `-l` / `--log-level` | 保留的日志级别参数，当前服务使用 `info`（`2`）。 |

## 文档模型下载与离线使用

首次解析或启动服务时，Cosmic 会从 ModelScope 下载所需模型。离线使用时，在联网机器上安装 Git LFS 后，先下载完整模型目录。

```cmd
git lfs install
git clone https://www.modelscope.cn/cjasqwd/cosmic-models.git "C:\models\cosmic"
git -C "C:\models\cosmic" lfs pull
```

将整个模型目录复制到离线机器，在启动 Cosmic 前设置模型路径并跳过联网下载。Windows CMD 示例使用 `C:\models\cosmic`。

```cmd
set "COSMIC_MODEL_PATH=C:\models\cosmic"
set "COSMIC_SKIP_DOWNLOAD_MODEL=1"
```

在 Linux 上，将目录复制到相应的绝对路径，再用 `export` 设置变量。

```bash
export COSMIC_MODEL_PATH=/opt/cosmic/models
export COSMIC_SKIP_DOWNLOAD_MODEL=1
```
