seanpedrick-case/doc_redaction
GitHub: seanpedrick-case/doc_redaction
「doc_redaction」是一个用于从多种文档中脱敏个人信息的工具，以保障隐私和合规性。
Stars: 50 | Forks: 10
## 标题：文档脱敏
emoji: 📝
colorFrom: blue
colorTo: yellow
sdk: docker
app_file: app.py
pinned: true
license: agpl-3.0
short_description: 对PDF文档和表格数据进行OCR/脱敏处理
# 文档脱敏 (doc_redaction)
对文档（PDF、PNG、JPG）、Word文件（DOCX）或表格数据（XLSX/CSV/Parquet）中的个人身份信息（PII）进行脱敏处理。请参阅[用户指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)，了解应用所有功能的完整使用流程。
## 🚀 快速开始 - 安装与首次运行
按照以下说明在你的本地机器上运行文档脱敏应用。
### 1. 软件包安装
#### 选项 1 - 推荐：从源代码仓库安装
克隆仓库并以可编辑模式安装：
```
git clone https://github.com/seanpedrick-case/doc_redaction.git
cd doc_redaction
pip install -e .
```
##### 安装额外依赖（Paddle或Transformers/Torch VLM）
要使用PaddleOCR进行安装：
```
pip install -e ".[paddle]"
```
请注意，默认安装的PaddleOCR和Torch版本均为仅CPU版本。如果你想安装对应的GPU版本，需要运行以下命令：
```
pip install paddlepaddle-gpu==3.2.1 --index-url https://www.paddlepaddle.org.cn/packages/stable/cu129/
```
如果你想使用transformers包运行VLMs / LLMs：
```
pip install -e ".[vlm]"
```
**注意：** 在同一环境中同时运行paddlepaddle gpu和torch比较困难。你可能需要重新安装cpu版本以确保兼容性，并在一个没有安装torch的独立环境中运行paddlepaddle-gpu。如果在安装paddle gpu后出现与.dll文件相关的错误，你可能需要安装最新的c++可再发行组件。对于Windows系统，你可以在[这里](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)找到它们。
```
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu129
pip install torchvision --index-url https://download.pytorch.org/whl/cu129
```
#### 选项 2 - 从PyPI安装
创建一个虚拟环境（推荐）并安装 **doc_redaction**。
```
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux：
source venv/bin/activate
```
该软件包在PyPI上发布为 **`doc-redaction`**（导入名为 **`doc_redaction`**）：
```
pip install doc_redaction
```
可选额外依赖（与`pyproject.toml`中相同）。用于安装paddleOCR：
```
pip install "doc_redaction[paddle]"
```
用于使用transformers包运行VLMs / LLMs：
```
pip install "doc_redaction[vlm]"
```
要以编程方式使用（CLI优先，API路由与Gradio的`api_name`对应），请参阅 **[Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)**。安装后，控制台脚本 **`cli_redact`** 即可使用。
**通过PyPI安装启动Web UI：** 你可以*通过* `pip install doc_redaction` 后运行以下命令来启动Gradio UI（请注意，前置条件tesseract和poppler需要按照下面的步骤2正确安装）：
```
python -m app
```
**重要：你的工作目录很重要。** 当你运行 `python -m app` 时，应用程序将你*当前的文件夹*视为“应用文件夹”：
- 它会从该文件夹中查找配置文件 `config/app_config.env`（`python -m doc_redaction.install_deps` 也会在那里写入 `config/app_config.env`）。
- 它可能会在该位置创建新的文件夹（例如 `config/`、`output/`、`input/`、`logs/`、`usage/`、`feedback/`，以及根据你的设置而定的临时/缓存文件夹）。
- UI示例文件和捆绑的资源已随PyPI安装一起打包（它们位于已安装的 `doc_redaction` 包内）。如果你在PyPI安装后从一个“随机”目录运行，应用程序仍然可以定位其打包的示例；你的工作目录主要影响 `config/`、`input/`、`output/`、日志和临时文件夹的创建位置。
实际上，**最流畅的UI体验**（示例、捆绑资源、文档链接、可预测的相对路径）通常仍然是通过**检出仓库**或**Docker**获得，但只要从一个合适的工作文件夹运行并具备系统依赖项（或先运行 `python -m doc_redaction.install_deps`），PyPI安装就足以启动UI。
#### 选项 3 - Docker安装
doc_redaction 脱敏应用可以使用仓库中提供的 [Dockerfile](https://github.com/seanpedrick-case/doc_redaction/blob/main/Dockerfile) 或Docker compose文件（[llama.cpp](https://github.com/ggml-org/llama.cpp)， [vLLM](https://docs.vllm.ai/en/stable/)）进行安装。
##### 配合 Llama.cpp / vLLM 推理服务器
该项目现在提供了Docker和Docker compose文件，可将脱敏应用与由 [llama.cpp](https://github.com/ggml-org/llama.cpp) 或 [vLLM](https://docs.vllm.ai/en/stable/) 驱动的本地推理服务器配对运行。对于显存较低的系统，Llama.cpp 比 vLLM 更灵活，因为 Llama.cpp 会自动将任务卸载到 CPU/系统内存，而不是像 vLLM 那样倾向于失败。
对于 Llama.cpp，你可以使用 [docker-compose_llama.yml](https://github.com/seanpedrick-case/doc_redaction/blob/main/docker-compose_llama.yml) 文件，对于 vLLM，你可以使用 [docker-compose_vllm.yml](https://github.com/seanpedrick-case/doc_redaction/blob/main/docker-compose_vllm.yml) 文件。要运行，需要安装 Docker / Docker Desktop，然后你可以运行文件顶部建议的命令来启动服务器。
根据从compose文件中选择的模型，你将需要大约40 GB的磁盘空间来运行所有内容。对于vLLM服务器，你需要24 GB显存。对于Llama.cpp服务器，24 GB显存可以全速运行，但Docker compose文件中的`n-gpu-layers`和`n-cpu-moe`参数可以进行调整以适应你的系统。我建议至少8 GB显存作为获得体面推理速度的最低要求。有关使用GGUF文件处理Qwen 3.5的更多详细信息，请参阅 [Unsloth指南](https://unsloth.ai/docs/models/qwen3.5)。
##### 不配合 Llama.cpp / vLLM 推理服务器
如果你想要一个不带GPU支持的可用Docker安装，可以从仓库中的 [Dockerfile](https://github.com/seanpedrick-case/doc_redaction/blob/main/Dockerfile) 进行安装。一个使用CPU版PaddleOCR的工作示例可以在 [Hugging Face](https://huggingface.co/spaces/seanpedrickcase/document_redaction) 上找到。你可以调整 `INSTALL_PADDLEOCR`、`PADDLE_GPU_ENABLED`、`INSTALL_VLM` 和 `TORCH_GPU_ENABLED` 配置变量，以调整用于本地VLM支持的PaddleOCR和Transformers包。请注意，GPU版PaddleOCR和GPU版Transformers/Torch通常不能很好地协同工作，这也是下面提供Llama.cpp/vLLM推理服务器Docker安装选项的原因之一。
### 2. 安装前置条件：Tesseract 和 Poppler
此应用程序依赖两个外部工具进行OCR（Tesseract）和PDF处理（Poppler）。请在继续之前在你的系统上安装它们。要成功运行文档脱敏应用，这些工具需要被安装，并且要么 1. 添加到系统PATH，要么 2. 放在一个在 `config/app_config.env` 文件中通过 `TESSERACT_FOLDER` 和 `POPPLER_FOLDER` 变量直接引用的文件夹中（如果你想查看代码，定义在[这里](https://github.com/seanpedrick-case/doc_redaction/blob/main/tools/config.py)）。以下说明将指导你完成安装这些依赖项的不同方法。
#### 自动化依赖设置（推荐）
如果你**没有管理员权限**（或者你只是想要最简单的设置），可以让项目将 **Tesseract** 和 **Poppler** 下载并配置到doc_redaction文件夹内的一个本地 `redaction_deps/` 文件夹中。
首先你需要安装脚本，这意味着你要么：
- **检出仓库**：`git clone ...` 并从仓库根目录运行命令（推荐用于Web UI），或者
- **PyPI安装**：`pip install doc_redaction` 并从一个你希望创建/更新 `redaction_deps/` 和 `config/app_config.env` 的可写文件夹运行。
创建/激活你的虚拟环境并安装Python依赖后，从仓库根目录（或你选择的工作文件夹）运行：
```
python -m doc_redaction.install_deps
```
这会将 `TESSERACT_FOLDER` / `POPPLER_FOLDER` 写入 `config/app_config.env`，这样应用程序无需你编辑系统PATH就能找到二进制文件。
要仅检查你的机器是否已经可以找到这些工具：
```
python -m doc_redaction.install_deps --verify-only
```
#### **在 Windows 上**
如果你不使用上面的自动化设置，可以通过下载安装程序并手动将程序添加到系统PATH来安装依赖项。
1. **安装 Tesseract OCR：**
* 从官方Tesseract [UB Mannheim页面](https://github.com/UB-Mannheim/tesseract/wiki) 下载安装程序（例如 `tesseract-ocr-w64-setup-v5.X.X...exe`）。
* 运行安装程序。
* **重要：** 安装期间，请确保选择“为所有用户添加Tesseract到系统PATH”或类似选项。这对于应用程序找到Tesseract可执行文件至关重要。
2. **安装 Poppler：**
* 下载适用于Windows的最新Poppler二进制文件。一个常见的来源是 [Poppler for Windows](https://github.com/oschwartz10612/poppler-windows) 的GitHub releases页面。下载 `.zip` 文件（例如 `poppler-25.07.0-win.zip`）。
* 将zip文件的内容解压缩到计算机上的永久位置，例如 `C:\Program Files\poppler\`。
* 你必须将Poppler安装目录下的 `bin` 文件夹添加到系统的PATH环境变量中。
* 在Windows开始菜单中搜索“编辑系统环境变量”并打开它。
* 点击“环境变量...”按钮。
* 在“系统变量”部分，找到并选择 `Path` 变量，然后点击“编辑...”。
* 点击“新建”并添加Poppler文件夹内 `bin` 目录的完整路径（例如 `C:\Program Files\poppler\poppler-24.02.0\bin`）。
* 点击所有窗口的“确定”以保存更改。
要进行验证，请打开一个新的命令提示符并运行 `tesseract --version` 和 `pdftoppm -v`。如果两者都返回版本信息，则表示你已成功安装前置条件。
#### **在 Linux (Debian/Ubuntu) 上**
打开你的终端并运行以下命令来安装Tesseract和Poppler：
```
sudo apt-get update && sudo apt-get install -y tesseract-ocr poppler-utils
```
#### **在 Linux (Fedora/CentOS/RHEL) 上**
打开你的终端并使用 `dnf` 或 `yum` 包管理器：
```
sudo dnf install -y tesseract poppler-utils
```
### 3. 运行应用程序
所有依赖项安装完毕后，你现在可以启动Gradio应用程序GUI。有关如何使用的指南，请前往[这里](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)。
```
python app.py
```
运行命令后，应用程序将启动，你将在终端中看到一个本地URL（通常是 `http://127.0.0.1:7860`）。
在你的网页浏览器中打开此URL即可使用文档脱敏工具。
#### 命令行接口
有关CLI命令示例，请参考[本指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html#command-line-interface-cli)或 [cli_redact.py](https://github.com/seanpedrick-case/doc_redaction/blob/main/cli_redact.py#L321) 中的示例。
如果你是从 **PyPI** 安装的，使用已安装的控制台脚本：
```
cli_redact --help
```
从 **检出仓库** 运行，你也可以执行：
```
python cli_redact.py --help
```
#### Python包命令
有关使用Python包的Python示例，请参阅 [Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)。
### 4. ⚙️ 配置（可选）
你可以通过创建配置文件来自定义应用程序的行为。这使你无需修改源代码即可更改设置，例如启用AWS功能、更改日志记录行为或指向本地Tesseract/Poppler安装。所有可以在 `app_config.env` 文件中修改的潜在设置的完整概览可以在 `tools/config.py` 中看到，解释在[github仓库](https://seanpedrick-case.github.io/doc_redaction/)的文档网站上。
开始操作：
1. 在项目根目录找到 `example_config.env` 文件。
2. 在 `config/` 目录内创建一个名为 `app_config.env` 的新文件（即 `config/app_config.env`）。
3. 将 `example_config.env` 的内容复制到你的新 `config/app_config.env` 文件中。
4. 根据你的需要修改 `config/app_config.env` 中的值。应用程序将在启动时自动加载这些设置。
如果你不创建此文件，应用程序将使用默认设置运行。
#### 配置项详解
以下是最重要的设置概览，按是否用于本地使用或需要AWS进行分类。
#### **本地与常规设置（无需AWS）**
这些设置对所有用户都有用，无论你是否使用AWS。
* `TESSERACT_FOLDER` / `POPPLER_FOLDER`
* 如果你将Tesseract或Poppler安装到 **Windows** 上的自定义位置且未将其添加到系统PATH，请使用这些设置。
* 提供相应安装文件夹的路径（对于Poppler，指向 `bin` 子目录）。
* **示例：** `POPPLER_FOLDER=C:/Program Files/poppler-24.02.0/bin/` `TESSERACT_FOLDER=tesseract/`
* `TESSERACT_DATA_FOLDER`
* 如果Tesseract运行但你看到类似 `Error opening data file ./eng.traineddata` 或 `Tesseract couldn't load any languages` 的错误，通常是因为它找不到 `tessdata/` 语言文件。
* 将此项设置为包含 `eng.traineddata` 的文件夹（通常是一个 `tessdata` 目录）。
* **示例 (Windows):** `TESSERACT_DATA_FOLDER=C:/Program Files/Tesseract-OCR/tessdata`
* `SHOW_LANGUAGE_SELECTION=True`
* 设置为 `True` 以在OCR处理的UI中显示语言选择下拉菜单。
* `DEFAULT_LOCAL_OCR_MODEL=tesseract`
* 选择本地OCR的后端。选项有 `tesseract`、`paddle` 或 `hybrid`。默认是 "Tesseract"，推荐使用。"hybrid-paddle" 是两者的结合 - 第一遍脱敏将使用Tesseract完成，然后第二遍将对置信度低的单词使用PaddleOCR。"paddle" 将仅返回整行文本提取，因此仅适用于OCR，不适用于脱敏。
* `SESSION_OUTPUT_FOLDER=False`
* 如果为 `True`，脱敏后的文件将为每个会话保存在 `output/` 目录内的唯一子文件夹中。
* `DISPLAY_FILE_NAMES_IN_LOGS=False`
* 出于隐私考虑，默认情况下，文件名不会记录在使用日志中。设置为 `True` 以包含它们。
#### **AWS 特定设置**
这些设置仅在你打算使用AWS服务（如用于OCR的Textract和用于PII检测的Comprehend）时才相关。
* `RUN_AWS_FUNCTIONS=True`
* **这是主开关。** 你必须将此项设置为 `True` 以启用任何AWS功能。如果为 `False`，所有其他AWS设置将被忽略。
* **UI 选项：**
* `SHOW_AWS_TEXT_EXTRACTION_OPTIONS=True`: 在文本提取下拉菜单中添加“AWS Textract”选项。
* `SHOW_AWS_PII_DETECTION_OPTIONS=True`: 在PII检测下拉菜单中添加“AWS Comprehend”选项。
* **核心 AWS 配置：**
* `AWS_REGION=example-region`: 设置你的AWS区域（例如 `us-east-1`）。
* `DOCUMENT_REDACTION_BUCKET=example-bucket`: 应用程序将用于临时文件存储和处理的S3存储桶名称。
* **AWS 日志记录：**
* `SAVE_LOGS_TO_DYNAMODB=True`: 如果启用，使用和反馈日志将保存到DynamoDB表中。
* `ACCESS_LOG_DYNAMODB_TABLE_NAME`, `USAGE_LOG_DYNAMODB_TABLE_NAME` 等：指定用于日志记录的DynamoDB表名。
* **高级 AWS Textract 功能：**
* `SHOW_WHOLE_DOCUMENT_TEXTRACT_CALL_OPTIONS=True`: 启用通过Textract进行大规模、异步文档处理的UI组件。
* `TEXTRACT_WHOLE_DOCUMENT_ANALYSIS_BUCKET=example-bucket-output`: 用于存放异步Textract作业最终输出的单独S3存储桶。
* `LOAD_PREVIOUS_TEXTRACT_JOBS_S3=True`: 如果启用，应用程序将尝试从S3加载先前提交的异步作业的状态。
* **成本跟踪（用于内部核算）：**
* `SHOW_COSTS=True`: 显示AWS操作的估计成本。即使AWS功能关闭也可以启用。
* `GET_COST_CODES=True`: 启用一个下拉菜单，让用户在运行作业前选择成本代码。
* `COST_CODES_PATH=config/cost_codes.csv`: 包含成本代码的CSV文件的本地路径。
* `ENFORCE_COST_CODES=True`: 在开始脱敏前强制要求选择成本代码。
现在你已经安装了应用，请参考[用户指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)获取有关如何将其用于基本和高级脱敏的更多信息。
## 面向代理（API快速入门）
如果你是一个通过HTTP与此应用程序交互的LLM/代理（例如Hugging Face Spaces），**不要从UI猜测输入**。使用Gradio模式作为事实来源：
- **发现模式**：`GET /gradio_api/info`
- **上传文件**：`POST /gradio_api/upload`（多部分字段 `files`）→ 返回服务器内部路径，如 `/tmp/gradio_tmp/...`
- **调用**：`POST /gradio_api/call/{api_name}`，请求体为 `{"data":[...]}`（参数顺序必须与 `/gradio_api/info` 匹配）
- **轮询**：`GET /gradio_api/call/{api_name}/{event_id}` 直到完成
- **下载输出**：`GET /gradio_api/file={path}`（注意：某些部署在没有会话cookie的情况下返回403）
### 选择正确的路由（优先使用简短的 `gr.api` 端点）
获取 `/gradio_api/info`，然后优先使用存在的最简单路由：
- **将编辑过的审查CSV应用到PDF**：`/review_apply`
- **对PDF/图像文档进行脱敏**：`/doc_redact`
- **总结PDF**：`/pdf_summarise`
- **对表格文件（CSV/XLSX/Parquet/DOCX）进行脱敏**：`/tabular_redact`
如果这些端点在你的部署中不存在，则回退到长UI链式路由（`/apply_review_redactions`、`/redact_data` 等），并严格按照 `/gradio_api/info` 构建 `data[]`。
### 常见问题
- **参数数量错误** (`needed: N, got: M`) 表示你使用了错误的 `data[]` 调用了会话密集型UI处理器。请优先使用上述简短端点。
- **`handle_file()` 陷阱**（针对 `gradio_client` 用户）：**不要**用 `handle_file()` 包装服务器内部上传路径（例如 `/tmp/gradio_tmp/...`）。将它们作为普通字符串传递。
- **仅限容器的输出**：输出可能写入容器路径（例如 `/home/user/app/output/`）。计划通过 `file=...` 下载或在Docker中使用挂载的输出目录。
### 可选：MCP 服务器
如果你想让外部代理可靠地调用此应用，而无需重新实现Gradio的上传/调用/轮询/下载细节，可以考虑一个 **MCP 服务器**，它将主要任务（`redact_document`、`apply_review_redactions`、`redact_tabular`、`summarise_document`）包装在一个小工具接口后面。请参阅[相关文档](https://github.com/seanpedrick-case/doc_redaction/blob/main/mcp_doc_redaction/README.md)。
**作为库使用：** 从 [PyPI](https://pypi.org/project/doc-redaction/) 安装后（`pip install doc_redaction`），你可以从Python中调用与Gradio `api_name` 路由相同的工作流程。请参阅文档：[Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)。
要从文档中提取文本，“本地”选项包括用于可选择文本PDF的PikePDF和使用Tesseract进行OCR。使用AWS Textract可以提取更复杂的元素，例如手写、签名或不清晰的文本。也支持PaddleOCR和VLM（请参阅下面的安装说明）。
对于PII识别，“本地”（基于spaCy）在寻找常见名称、术语或要脱敏的自定义术语列表（请参阅脱敏设置）时能提供良好的效果。AWS Comprehend以较低的成本提供更好的结果。
“脱敏设置”上的其他选项包括：要脱敏的信息类型（例如人名、地名）、要包含/排除在脱敏之外的自定义术语、模糊匹配、语言设置和整页脱敏。脱敏完成后，你可以在“审查脱敏”选项卡上查看和修改建议的脱敏项，以快速创建最终的脱敏文档。
**注意：** 该应用并非100%准确，它会遗漏一些个人信息。在使用最终输出之前，**必须由人工**审查所有输出。
对文档（PDF、PNG、JPG）、Word文件（DOCX）或表格数据（XLSX/CSV/Parquet）中的个人身份信息（PII）进行脱敏处理。请参阅[用户指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)，了解应用所有功能的完整使用流程。
## 🚀 快速开始 - 安装与首次运行
按照以下说明在你的本地机器上运行文档脱敏应用。
### 1. 软件包安装
#### 选项 1 - 推荐：从源代码仓库安装
克隆仓库并以可编辑模式安装：
```
git clone https://github.com/seanpedrick-case/doc_redaction.git
cd doc_redaction
pip install -e .
```
##### 安装额外依赖（Paddle或Transformers/Torch VLM）
要使用PaddleOCR进行安装：
```
pip install -e ".[paddle]"
```
请注意，默认安装的PaddleOCR和Torch版本均为仅CPU版本。如果你想安装对应的GPU版本，需要运行以下命令：
```
pip install paddlepaddle-gpu==3.2.1 --index-url https://www.paddlepaddle.org.cn/packages/stable/cu129/
```
如果你想使用transformers包运行VLMs / LLMs：
```
pip install -e ".[vlm]"
```
**注意：** 在同一环境中同时运行paddlepaddle gpu和torch比较困难。你可能需要重新安装cpu版本以确保兼容性，并在一个没有安装torch的独立环境中运行paddlepaddle-gpu。如果在安装paddle gpu后出现与.dll文件相关的错误，你可能需要安装最新的c++可再发行组件。对于Windows系统，你可以在[这里](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170)找到它们。
```
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu129
pip install torchvision --index-url https://download.pytorch.org/whl/cu129
```
#### 选项 2 - 从PyPI安装
创建一个虚拟环境（推荐）并安装 **doc_redaction**。
```
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux：
source venv/bin/activate
```
该软件包在PyPI上发布为 **`doc-redaction`**（导入名为 **`doc_redaction`**）：
```
pip install doc_redaction
```
可选额外依赖（与`pyproject.toml`中相同）。用于安装paddleOCR：
```
pip install "doc_redaction[paddle]"
```
用于使用transformers包运行VLMs / LLMs：
```
pip install "doc_redaction[vlm]"
```
要以编程方式使用（CLI优先，API路由与Gradio的`api_name`对应），请参阅 **[Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)**。安装后，控制台脚本 **`cli_redact`** 即可使用。
**通过PyPI安装启动Web UI：** 你可以*通过* `pip install doc_redaction` 后运行以下命令来启动Gradio UI（请注意，前置条件tesseract和poppler需要按照下面的步骤2正确安装）：
```
python -m app
```
**重要：你的工作目录很重要。** 当你运行 `python -m app` 时，应用程序将你*当前的文件夹*视为“应用文件夹”：
- 它会从该文件夹中查找配置文件 `config/app_config.env`（`python -m doc_redaction.install_deps` 也会在那里写入 `config/app_config.env`）。
- 它可能会在该位置创建新的文件夹（例如 `config/`、`output/`、`input/`、`logs/`、`usage/`、`feedback/`，以及根据你的设置而定的临时/缓存文件夹）。
- UI示例文件和捆绑的资源已随PyPI安装一起打包（它们位于已安装的 `doc_redaction` 包内）。如果你在PyPI安装后从一个“随机”目录运行，应用程序仍然可以定位其打包的示例；你的工作目录主要影响 `config/`、`input/`、`output/`、日志和临时文件夹的创建位置。
实际上，**最流畅的UI体验**（示例、捆绑资源、文档链接、可预测的相对路径）通常仍然是通过**检出仓库**或**Docker**获得，但只要从一个合适的工作文件夹运行并具备系统依赖项（或先运行 `python -m doc_redaction.install_deps`），PyPI安装就足以启动UI。
#### 选项 3 - Docker安装
doc_redaction 脱敏应用可以使用仓库中提供的 [Dockerfile](https://github.com/seanpedrick-case/doc_redaction/blob/main/Dockerfile) 或Docker compose文件（[llama.cpp](https://github.com/ggml-org/llama.cpp)， [vLLM](https://docs.vllm.ai/en/stable/)）进行安装。
##### 配合 Llama.cpp / vLLM 推理服务器
该项目现在提供了Docker和Docker compose文件，可将脱敏应用与由 [llama.cpp](https://github.com/ggml-org/llama.cpp) 或 [vLLM](https://docs.vllm.ai/en/stable/) 驱动的本地推理服务器配对运行。对于显存较低的系统，Llama.cpp 比 vLLM 更灵活，因为 Llama.cpp 会自动将任务卸载到 CPU/系统内存，而不是像 vLLM 那样倾向于失败。
对于 Llama.cpp，你可以使用 [docker-compose_llama.yml](https://github.com/seanpedrick-case/doc_redaction/blob/main/docker-compose_llama.yml) 文件，对于 vLLM，你可以使用 [docker-compose_vllm.yml](https://github.com/seanpedrick-case/doc_redaction/blob/main/docker-compose_vllm.yml) 文件。要运行，需要安装 Docker / Docker Desktop，然后你可以运行文件顶部建议的命令来启动服务器。
根据从compose文件中选择的模型，你将需要大约40 GB的磁盘空间来运行所有内容。对于vLLM服务器，你需要24 GB显存。对于Llama.cpp服务器，24 GB显存可以全速运行，但Docker compose文件中的`n-gpu-layers`和`n-cpu-moe`参数可以进行调整以适应你的系统。我建议至少8 GB显存作为获得体面推理速度的最低要求。有关使用GGUF文件处理Qwen 3.5的更多详细信息，请参阅 [Unsloth指南](https://unsloth.ai/docs/models/qwen3.5)。
##### 不配合 Llama.cpp / vLLM 推理服务器
如果你想要一个不带GPU支持的可用Docker安装，可以从仓库中的 [Dockerfile](https://github.com/seanpedrick-case/doc_redaction/blob/main/Dockerfile) 进行安装。一个使用CPU版PaddleOCR的工作示例可以在 [Hugging Face](https://huggingface.co/spaces/seanpedrickcase/document_redaction) 上找到。你可以调整 `INSTALL_PADDLEOCR`、`PADDLE_GPU_ENABLED`、`INSTALL_VLM` 和 `TORCH_GPU_ENABLED` 配置变量，以调整用于本地VLM支持的PaddleOCR和Transformers包。请注意，GPU版PaddleOCR和GPU版Transformers/Torch通常不能很好地协同工作，这也是下面提供Llama.cpp/vLLM推理服务器Docker安装选项的原因之一。
### 2. 安装前置条件：Tesseract 和 Poppler
此应用程序依赖两个外部工具进行OCR（Tesseract）和PDF处理（Poppler）。请在继续之前在你的系统上安装它们。要成功运行文档脱敏应用，这些工具需要被安装，并且要么 1. 添加到系统PATH，要么 2. 放在一个在 `config/app_config.env` 文件中通过 `TESSERACT_FOLDER` 和 `POPPLER_FOLDER` 变量直接引用的文件夹中（如果你想查看代码，定义在[这里](https://github.com/seanpedrick-case/doc_redaction/blob/main/tools/config.py)）。以下说明将指导你完成安装这些依赖项的不同方法。
#### 自动化依赖设置（推荐）
如果你**没有管理员权限**（或者你只是想要最简单的设置），可以让项目将 **Tesseract** 和 **Poppler** 下载并配置到doc_redaction文件夹内的一个本地 `redaction_deps/` 文件夹中。
首先你需要安装脚本，这意味着你要么：
- **检出仓库**：`git clone ...` 并从仓库根目录运行命令（推荐用于Web UI），或者
- **PyPI安装**：`pip install doc_redaction` 并从一个你希望创建/更新 `redaction_deps/` 和 `config/app_config.env` 的可写文件夹运行。
创建/激活你的虚拟环境并安装Python依赖后，从仓库根目录（或你选择的工作文件夹）运行：
```
python -m doc_redaction.install_deps
```
这会将 `TESSERACT_FOLDER` / `POPPLER_FOLDER` 写入 `config/app_config.env`，这样应用程序无需你编辑系统PATH就能找到二进制文件。
要仅检查你的机器是否已经可以找到这些工具：
```
python -m doc_redaction.install_deps --verify-only
```
#### **在 Windows 上**
如果你不使用上面的自动化设置，可以通过下载安装程序并手动将程序添加到系统PATH来安装依赖项。
1. **安装 Tesseract OCR：**
* 从官方Tesseract [UB Mannheim页面](https://github.com/UB-Mannheim/tesseract/wiki) 下载安装程序（例如 `tesseract-ocr-w64-setup-v5.X.X...exe`）。
* 运行安装程序。
* **重要：** 安装期间，请确保选择“为所有用户添加Tesseract到系统PATH”或类似选项。这对于应用程序找到Tesseract可执行文件至关重要。
2. **安装 Poppler：**
* 下载适用于Windows的最新Poppler二进制文件。一个常见的来源是 [Poppler for Windows](https://github.com/oschwartz10612/poppler-windows) 的GitHub releases页面。下载 `.zip` 文件（例如 `poppler-25.07.0-win.zip`）。
* 将zip文件的内容解压缩到计算机上的永久位置，例如 `C:\Program Files\poppler\`。
* 你必须将Poppler安装目录下的 `bin` 文件夹添加到系统的PATH环境变量中。
* 在Windows开始菜单中搜索“编辑系统环境变量”并打开它。
* 点击“环境变量...”按钮。
* 在“系统变量”部分，找到并选择 `Path` 变量，然后点击“编辑...”。
* 点击“新建”并添加Poppler文件夹内 `bin` 目录的完整路径（例如 `C:\Program Files\poppler\poppler-24.02.0\bin`）。
* 点击所有窗口的“确定”以保存更改。
要进行验证，请打开一个新的命令提示符并运行 `tesseract --version` 和 `pdftoppm -v`。如果两者都返回版本信息，则表示你已成功安装前置条件。
#### **在 Linux (Debian/Ubuntu) 上**
打开你的终端并运行以下命令来安装Tesseract和Poppler：
```
sudo apt-get update && sudo apt-get install -y tesseract-ocr poppler-utils
```
#### **在 Linux (Fedora/CentOS/RHEL) 上**
打开你的终端并使用 `dnf` 或 `yum` 包管理器：
```
sudo dnf install -y tesseract poppler-utils
```
### 3. 运行应用程序
所有依赖项安装完毕后，你现在可以启动Gradio应用程序GUI。有关如何使用的指南，请前往[这里](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)。
```
python app.py
```
运行命令后，应用程序将启动，你将在终端中看到一个本地URL（通常是 `http://127.0.0.1:7860`）。
在你的网页浏览器中打开此URL即可使用文档脱敏工具。
#### 命令行接口
有关CLI命令示例，请参考[本指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html#command-line-interface-cli)或 [cli_redact.py](https://github.com/seanpedrick-case/doc_redaction/blob/main/cli_redact.py#L321) 中的示例。
如果你是从 **PyPI** 安装的，使用已安装的控制台脚本：
```
cli_redact --help
```
从 **检出仓库** 运行，你也可以执行：
```
python cli_redact.py --help
```
#### Python包命令
有关使用Python包的Python示例，请参阅 [Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)。
### 4. ⚙️ 配置（可选）
你可以通过创建配置文件来自定义应用程序的行为。这使你无需修改源代码即可更改设置，例如启用AWS功能、更改日志记录行为或指向本地Tesseract/Poppler安装。所有可以在 `app_config.env` 文件中修改的潜在设置的完整概览可以在 `tools/config.py` 中看到，解释在[github仓库](https://seanpedrick-case.github.io/doc_redaction/)的文档网站上。
开始操作：
1. 在项目根目录找到 `example_config.env` 文件。
2. 在 `config/` 目录内创建一个名为 `app_config.env` 的新文件（即 `config/app_config.env`）。
3. 将 `example_config.env` 的内容复制到你的新 `config/app_config.env` 文件中。
4. 根据你的需要修改 `config/app_config.env` 中的值。应用程序将在启动时自动加载这些设置。
如果你不创建此文件，应用程序将使用默认设置运行。
#### 配置项详解
以下是最重要的设置概览，按是否用于本地使用或需要AWS进行分类。
#### **本地与常规设置（无需AWS）**
这些设置对所有用户都有用，无论你是否使用AWS。
* `TESSERACT_FOLDER` / `POPPLER_FOLDER`
* 如果你将Tesseract或Poppler安装到 **Windows** 上的自定义位置且未将其添加到系统PATH，请使用这些设置。
* 提供相应安装文件夹的路径（对于Poppler，指向 `bin` 子目录）。
* **示例：** `POPPLER_FOLDER=C:/Program Files/poppler-24.02.0/bin/` `TESSERACT_FOLDER=tesseract/`
* `TESSERACT_DATA_FOLDER`
* 如果Tesseract运行但你看到类似 `Error opening data file ./eng.traineddata` 或 `Tesseract couldn't load any languages` 的错误，通常是因为它找不到 `tessdata/` 语言文件。
* 将此项设置为包含 `eng.traineddata` 的文件夹（通常是一个 `tessdata` 目录）。
* **示例 (Windows):** `TESSERACT_DATA_FOLDER=C:/Program Files/Tesseract-OCR/tessdata`
* `SHOW_LANGUAGE_SELECTION=True`
* 设置为 `True` 以在OCR处理的UI中显示语言选择下拉菜单。
* `DEFAULT_LOCAL_OCR_MODEL=tesseract`
* 选择本地OCR的后端。选项有 `tesseract`、`paddle` 或 `hybrid`。默认是 "Tesseract"，推荐使用。"hybrid-paddle" 是两者的结合 - 第一遍脱敏将使用Tesseract完成，然后第二遍将对置信度低的单词使用PaddleOCR。"paddle" 将仅返回整行文本提取，因此仅适用于OCR，不适用于脱敏。
* `SESSION_OUTPUT_FOLDER=False`
* 如果为 `True`，脱敏后的文件将为每个会话保存在 `output/` 目录内的唯一子文件夹中。
* `DISPLAY_FILE_NAMES_IN_LOGS=False`
* 出于隐私考虑，默认情况下，文件名不会记录在使用日志中。设置为 `True` 以包含它们。
#### **AWS 特定设置**
这些设置仅在你打算使用AWS服务（如用于OCR的Textract和用于PII检测的Comprehend）时才相关。
* `RUN_AWS_FUNCTIONS=True`
* **这是主开关。** 你必须将此项设置为 `True` 以启用任何AWS功能。如果为 `False`，所有其他AWS设置将被忽略。
* **UI 选项：**
* `SHOW_AWS_TEXT_EXTRACTION_OPTIONS=True`: 在文本提取下拉菜单中添加“AWS Textract”选项。
* `SHOW_AWS_PII_DETECTION_OPTIONS=True`: 在PII检测下拉菜单中添加“AWS Comprehend”选项。
* **核心 AWS 配置：**
* `AWS_REGION=example-region`: 设置你的AWS区域（例如 `us-east-1`）。
* `DOCUMENT_REDACTION_BUCKET=example-bucket`: 应用程序将用于临时文件存储和处理的S3存储桶名称。
* **AWS 日志记录：**
* `SAVE_LOGS_TO_DYNAMODB=True`: 如果启用，使用和反馈日志将保存到DynamoDB表中。
* `ACCESS_LOG_DYNAMODB_TABLE_NAME`, `USAGE_LOG_DYNAMODB_TABLE_NAME` 等：指定用于日志记录的DynamoDB表名。
* **高级 AWS Textract 功能：**
* `SHOW_WHOLE_DOCUMENT_TEXTRACT_CALL_OPTIONS=True`: 启用通过Textract进行大规模、异步文档处理的UI组件。
* `TEXTRACT_WHOLE_DOCUMENT_ANALYSIS_BUCKET=example-bucket-output`: 用于存放异步Textract作业最终输出的单独S3存储桶。
* `LOAD_PREVIOUS_TEXTRACT_JOBS_S3=True`: 如果启用，应用程序将尝试从S3加载先前提交的异步作业的状态。
* **成本跟踪（用于内部核算）：**
* `SHOW_COSTS=True`: 显示AWS操作的估计成本。即使AWS功能关闭也可以启用。
* `GET_COST_CODES=True`: 启用一个下拉菜单，让用户在运行作业前选择成本代码。
* `COST_CODES_PATH=config/cost_codes.csv`: 包含成本代码的CSV文件的本地路径。
* `ENFORCE_COST_CODES=True`: 在开始脱敏前强制要求选择成本代码。
现在你已经安装了应用，请参考[用户指南](https://seanpedrick-case.github.io/doc_redaction/src/user_guide.html)获取有关如何将其用于基本和高级脱敏的更多信息。
## 面向代理（API快速入门）
如果你是一个通过HTTP与此应用程序交互的LLM/代理（例如Hugging Face Spaces），**不要从UI猜测输入**。使用Gradio模式作为事实来源：
- **发现模式**：`GET /gradio_api/info`
- **上传文件**：`POST /gradio_api/upload`（多部分字段 `files`）→ 返回服务器内部路径，如 `/tmp/gradio_tmp/...`
- **调用**：`POST /gradio_api/call/{api_name}`，请求体为 `{"data":[...]}`（参数顺序必须与 `/gradio_api/info` 匹配）
- **轮询**：`GET /gradio_api/call/{api_name}/{event_id}` 直到完成
- **下载输出**：`GET /gradio_api/file={path}`（注意：某些部署在没有会话cookie的情况下返回403）
### 选择正确的路由（优先使用简短的 `gr.api` 端点）
获取 `/gradio_api/info`，然后优先使用存在的最简单路由：
- **将编辑过的审查CSV应用到PDF**：`/review_apply`
- **对PDF/图像文档进行脱敏**：`/doc_redact`
- **总结PDF**：`/pdf_summarise`
- **对表格文件（CSV/XLSX/Parquet/DOCX）进行脱敏**：`/tabular_redact`
如果这些端点在你的部署中不存在，则回退到长UI链式路由（`/apply_review_redactions`、`/redact_data` 等），并严格按照 `/gradio_api/info` 构建 `data[]`。
### 常见问题
- **参数数量错误** (`needed: N, got: M`) 表示你使用了错误的 `data[]` 调用了会话密集型UI处理器。请优先使用上述简短端点。
- **`handle_file()` 陷阱**（针对 `gradio_client` 用户）：**不要**用 `handle_file()` 包装服务器内部上传路径（例如 `/tmp/gradio_tmp/...`）。将它们作为普通字符串传递。
- **仅限容器的输出**：输出可能写入容器路径（例如 `/home/user/app/output/`）。计划通过 `file=...` 下载或在Docker中使用挂载的输出目录。
### 可选：MCP 服务器
如果你想让外部代理可靠地调用此应用，而无需重新实现Gradio的上传/调用/轮询/下载细节，可以考虑一个 **MCP 服务器**，它将主要任务（`redact_document`、`apply_review_redactions`、`redact_tabular`、`summarise_document`）包装在一个小工具接口后面。请参阅[相关文档](https://github.com/seanpedrick-case/doc_redaction/blob/main/mcp_doc_redaction/README.md)。
**作为库使用：** 从 [PyPI](https://pypi.org/project/doc-redaction/) 安装后（`pip install doc_redaction`），你可以从Python中调用与Gradio `api_name` 路由相同的工作流程。请参阅文档：[Python包使用说明（Python）](https://seanpedrick-case.github.io/doc_redaction/src/python_package_usage.html)。
要从文档中提取文本，“本地”选项包括用于可选择文本PDF的PikePDF和使用Tesseract进行OCR。使用AWS Textract可以提取更复杂的元素，例如手写、签名或不清晰的文本。也支持PaddleOCR和VLM（请参阅下面的安装说明）。
对于PII识别，“本地”（基于spaCy）在寻找常见名称、术语或要脱敏的自定义术语列表（请参阅脱敏设置）时能提供良好的效果。AWS Comprehend以较低的成本提供更好的结果。
“脱敏设置”上的其他选项包括：要脱敏的信息类型（例如人名、地名）、要包含/排除在脱敏之外的自定义术语、模糊匹配、语言设置和整页脱敏。脱敏完成后，你可以在“审查脱敏”选项卡上查看和修改建议的脱敏项，以快速创建最终的脱敏文档。
**注意：** 该应用并非100%准确，它会遗漏一些个人信息。在使用最终输出之前，**必须由人工**审查所有输出。标签：Apex, CSV编辑, Docker, Excel编辑, Hugging Face, meg, OCR, PaddleOCR, PDF编辑, Python, PyTorch, Web演示, Word编辑, 个人可识别信息处理, 二进制发布, 信息安全, 凭据扫描, 图像编辑, 图形用户界面, 多格式支持, 安全防御评估, 开源工具, 批量处理, 敏感信息去标识化, 文件处理, 文档编辑, 无后门, 机器学习, 漏洞利用检测, 系统调用监控, 网络安全, 视觉语言模型, 请求拦截, 逆向工具, 隐私保护