内容
# 通用 AI 转换器
将文档、图像、音频和视频转换为 Markdown 或结构化 JSON。核心与代理无关：可从终端、Python、HTTP API、MCP 兼容的 AI 代理、Docker 或您自己的应用程序使用。
## 一键安装 Codex
安装程序创建隔离环境，安装所有转换功能，安装 Codex 插件，并启用自动文件路由。
Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.ps1 | iex
```
macOS 或 Linux:
```bash
curl -fsSL https://raw.githubusercontent.com/KOLRNCH/Universal-AI-Converter/main/install.sh | sh
```
要求：Python 3.10+ 和 Codex。重启 Codex 并在安装后打开新任务。附加文件并提出常规问题；插件会自动选择转换器。
FFmpeg 和 Tesseract 是系统程序。Python 功能会自动安装，而安装程序会在使用该格式时报告任何缺少的系统可执行文件。
## 为什么它可移植
- 不依赖 Codex、ChatGPT、Claude 或特定 LLM。
- 稳定的 Python API 和命令行界面形成核心。
- MCP 是兼容代理的可选适配器。
- HTTP 是其他所有适配器的可选适配器。
- 只有需要时才会安装大量文档、OCR 和语音依赖项。
## 安装
需要 Python 3.10 或更高版本。
```bash
pip install universal-ai-converter
pip install "universal-ai-converter[documents]"
pip install "universal-ai-converter[ocr]"
pip install "universal-ai-converter[media]"
pip install "universal-ai-converter[all]"
```
在第一个 PyPI 版本发布之前，直接从 GitHub 安装：
```bash
pip install "universal-ai-converter[all] @ git+https://github.com/KOLRNCH/Universal-AI-Converter.git"
```
OCR 还需要 Tesseract 可执行文件。视频还需要 FFmpeg。两者都必须在 `PATH` 中可用。
从此存储库进行开发：
```bash
python -m venv .venv
pip install -e ".[dev]"
pytest
```
## 命令行
```bash
uac convert report.pdf -o report.md
uac convert interview.mp4 -o transcript.md --whisper-model small
uac convert scan.png --format json -o result.json
```
## Python
```python
from universal_ai_converter import Converter
result = Converter().convert("report.pdf")
print(result.text)
```
## HTTP API
```bash
pip install "universal-ai-converter[api,documents]"
uac serve --host 127.0.0.1 --port 8765
curl -F "file=@report.pdf" http://127.0.0.1:8765/convert
```
## 任意 MCP 兼容代理
```bash
pip install "universal-ai-converter[mcp,documents]"
uac-mcp
```
在代理的配置中注册 `uac-mcp` 为 stdio MCP 服务器。代理接收到 `convert_file` 工具。确切的配置因客户端而异，因此热门代理的示例将存放在 `docs/integrations/` 中。
参见[通用 MCP 设置](docs/integrations/mcp.md)以获取可重用的配置示例。
## Docker
```bash
docker build -t universal-ai-converter .
docker run --rm -p 127.0.0.1:8765:8765 universal-ai-converter
```
然后将文件上传到 `http://127.0.0.1:8765/convert`。faster-whisper 下载的模型文件应安装在持久缓存中，以便重复进行媒体转换。
## 格式路由
| 输入 | 后端 |
|---|---|
| PDF、DOCX、PPTX、XLSX、HTML、EPUB、ZIP、MSG | MarkItDown |
| PNG、JPEG、TIFF、WebP | Tesseract OCR |
| MP3、WAV、M4A、FLAC、OGG | faster-whisper |
| MP4、MKV、MOV、WebM、AVI | FFmpeg + faster-whisper |
| TXT、Markdown、CSV、JSON、XML、YAML | 内置文本读取器 |
## 安全
HTTP 服务器默认绑定到 localhost。转换库处理不受信任的文件，因此公共部署应在隔离容器中运行，并设置文件大小、时间、CPU 和内存限制。不要将开发服务器直接暴露在互联网上。
## 路线图
- 第三方转换器的插件入口点
- 递归存档和批量转换
- URL 和 YouTube 适配器
- Docker 镜像和跨平台桌面应用程序
- 可配置的 OCR 语言和带时间戳的转录
- 沙盒生产工作器
## 许可证
MIT
