Skip to content

Commit e655b49

Browse files
begoniezhaobegoniezhao
committed
docs: Update README and FAQ for config, OCR, and troubleshooting
1 parent 88fd42c commit e655b49

File tree

2 files changed

+241
-30
lines changed

2 files changed

+241
-30
lines changed

‎docreader/README.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# DocReader Service
2+
3+
DocReader 是 WeKnora 项目中负责文档解析和处理的 gRPC 服务。它支持多种文档格式的读取、OCR 识别、多模态处理等功能。
4+
5+
## Docker Compose 环境变量配置
6+
7+
在 `docker-compose.yml` 文件中，docreader 服务配置了以下环境变量：
8+
9+
```yaml
10+
docreader:
11+
image: wechatopenai/weknora-docreader:${WEKNORA_VERSION:-latest}
12+
environment:
13+
- MINIO_ENDPOINT=minio:9000
14+
- MINIO_PUBLIC_ENDPOINT=http://localhost:${MINIO_PORT:-9000}
15+
- MINERU_ENDPOINT=${MINERU_ENDPOINT:-}
16+
- MAX_FILE_SIZE_MB=${MAX_FILE_SIZE_MB:-}
17+
```
18+
19+
### 环境变量说明
20+
21+
#### 1. MINIO_ENDPOINT
22+
23+
- **说明**: MinIO 服务的内部访问地址（容器间通信）
24+
- **默认值**: `minio:9000`
25+
- **用途**: DocReader 服务使用此地址连接到 MinIO 对象存储服务，用于读取和存储文档处理过程中的文件
26+
- **配置示例**:
27+
```yaml
28+
- MINIO_ENDPOINT=minio:9000 # Docker 网络内部地址
29+
```
30+
31+
#### 2. MINIO_PUBLIC_ENDPOINT
32+
33+
- **说明**: MinIO 服务的公开访问地址（外部访问）
34+
- **默认值**: `http://localhost:9000`
35+
- **用途**: 用于生成可从外部访问的文件 URL，例如在文档解析后返回图片链接时使用
36+
- **重要提示**:
37+
- 如果需要从其他设备或容器访问，需要将 `localhost` 替换为实际的 IP 地址
38+
- 可以在 `.env` 文件中配置 `MINIO_PORT` 来自定义端口
39+
- **配置示例**:
40+
```bash
41+
# .env 文件
42+
MINIO_PORT=9000
43+
```
44+
或直接在 docker-compose.yml 中修改：
45+
```yaml
46+
- MINIO_PUBLIC_ENDPOINT=http://192.168.1.100:9000 # 使用实际 IP
47+
```
48+
49+
#### 3. MINERU_ENDPOINT
50+
51+
- **说明**: MinerU 服务的访问地址（可选）
52+
- **默认值**: 空（不使用 MinerU）
53+
- **用途**: MinerU 是一个高级文档解析服务，支持更复杂的文档结构识别和处理。配置此变量后，DocReader 可以调用 MinerU 进行文档解析
54+
- **配置示例**:
55+
```bash
56+
# .env 文件
57+
MINERU_ENDPOINT=http://mineru-service:8080
58+
```
59+
60+
#### 4. MAX_FILE_SIZE_MB
61+
62+
- **说明**: 允许上传的最大文件大小（单位：MB）
63+
- **默认值**: `50` MB
64+
- **用途**: 限制 gRPC 服务接收的文件大小，防止过大的文件导致服务崩溃或性能问题
65+
- **配置示例**:
66+
```bash
67+
# .env 文件
68+
MAX_FILE_SIZE_MB=100 # 允许最大 100MB 的文件
69+
```
70+
71+
## 其他可配置的环境变量
72+
73+
除了 docker-compose.yml 中已配置的变量外，DocReader 还支持以下环境变量（可根据需要添加）：
74+
75+
### gRPC 配置
76+
77+
- `DOCREADER_GRPC_MAX_WORKERS`: gRPC 服务的最大工作线程数（默认：4）
78+
- `DOCREADER_GRPC_PORT`: gRPC 服务监听端口（默认：50051）
79+
80+
### OCR 配置
81+
82+
- `OCR_BACKEND`: OCR 引擎后端，可选值：
83+
- `paddle`: 使用 PaddleOCR（默认）
84+
- `no_ocr`: 禁用 OCR 功能
85+
- `api`: 使用外部 OCR API
86+
- `OCR_API_BASE_URL`: 外部 OCR API 的基础 URL
87+
- `OCR_API_KEY`: 外部 OCR API 的密钥
88+
- `OCR_MODEL`: OCR 模型名称
89+
90+
**示例**：禁用 OCR 功能
91+
```yaml
92+
environment:
93+
- OCR_BACKEND=no_ocr
94+
```
95+
96+
### VLM（视觉语言模型）配置
97+
98+
用于图像理解和描述生成：
99+
100+
- `VLM_MODEL_BASE_URL`: VLM 模型的 API 地址
101+
- `VLM_MODEL_NAME`: VLM 模型名称
102+
- `VLM_MODEL_API_KEY`: VLM 模型的 API 密钥
103+
- `VLM_INTERFACE_TYPE`: 接口类型，可选值：`openai`（默认）或 `ollama`
104+
105+
### 存储配置
106+
107+
DocReader 支持多种存储后端：
108+
109+
#### MinIO/S3 存储（推荐）
110+
111+
- `STORAGE_TYPE`: 设置为 `minio`
112+
- `MINIO_ACCESS_KEY_ID`: MinIO 访问密钥 ID（默认：minioadmin）
113+
- `MINIO_SECRET_ACCESS_KEY`: MinIO 访问密钥（默认：minioadmin）
114+
- `MINIO_BUCKET_NAME`: MinIO 存储桶名称（默认：WeKnora）
115+
- `MINIO_PATH_PREFIX`: 文件路径前缀
116+
- `MINIO_USE_SSL`: 是否使用 SSL（默认：false）
117+
118+
#### 腾讯云 COS 存储
119+
120+
- `STORAGE_TYPE`: 设置为 `cos`
121+
- `COS_SECRET_ID`: COS 访问密钥 ID
122+
- `COS_SECRET_KEY`: COS 访问密钥
123+
- `COS_REGION`: COS 区域
124+
- `COS_BUCKET_NAME`: COS 存储桶名称
125+
- `COS_APP_ID`: COS 应用 ID
126+
- `COS_PATH_PREFIX`: 文件路径前缀
127+
- `COS_ENABLE_OLD_DOMAIN`: 是否使用旧域名（默认：true）
128+
129+
### 代理配置
130+
131+
如果需要通过代理访问外部服务：
132+
133+
- `EXTERNAL_HTTP_PROXY`: HTTP 代理地址
134+
- `EXTERNAL_HTTPS_PROXY`: HTTPS 代理地址
135+
136+
### 图像处理配置
137+
138+
- `IMAGE_MAX_CONCURRENT`: 图像处理的最大并发数（默认：1）
139+
140+
## 配置示例
141+
142+
### 基础配置（使用 MinIO）
143+
144+
```yaml
145+
docreader:
146+
environment:
147+
- MINIO_ENDPOINT=minio:9000
148+
- MINIO_PUBLIC_ENDPOINT=http://localhost:9000
149+
- MAX_FILE_SIZE_MB=50
150+
```
151+
152+
### 高级配置（启用 MinerU + 自定义 OCR）
153+
154+
```yaml
155+
docreader:
156+
environment:
157+
- MINIO_ENDPOINT=minio:9000
158+
- MINIO_PUBLIC_ENDPOINT=http://192.168.1.100:9000
159+
- MINERU_ENDPOINT=http://mineru:8080
160+
- MAX_FILE_SIZE_MB=100
161+
- OCR_BACKEND=paddle
162+
- VLM_MODEL_BASE_URL=http://ollama:11434
163+
- VLM_MODEL_NAME=llava
164+
- VLM_INTERFACE_TYPE=ollama
165+
```
166+
167+
### 使用腾讯云 COS
168+
169+
```yaml
170+
docreader:
171+
environment:
172+
- STORAGE_TYPE=cos
173+
- COS_SECRET_ID=your_secret_id
174+
- COS_SECRET_KEY=your_secret_key
175+
- COS_REGION=ap-guangzhou
176+
- COS_BUCKET_NAME=your-bucket
177+
- COS_APP_ID=your_app_id
178+
- MAX_FILE_SIZE_MB=50
179+
```
180+
181+
## 常见问题
182+
183+
### 1. DocReader 服务无法启动？
184+
185+
如果日志中出现 PaddleOCR 相关错误，可以尝试禁用 OCR：
186+
187+
```yaml
188+
environment:
189+
- OCR_BACKEND=no_ocr
190+
```
191+
192+
### 2. 图片无法显示？
193+
194+
检查 `MINIO_PUBLIC_ENDPOINT` 配置：
195+
- 确保使用的是可从浏览器访问的地址
196+
- 如果从其他设备访问，不要使用 `localhost`，应使用实际 IP 地址
197+
198+
### 3. 文件上传失败？
199+
200+
检查 `MAX_FILE_SIZE_MB` 配置，确保限制足够大。同时需要确保前端和后端服务的文件大小限制保持一致。
201+
202+
## 服务健康检查
203+
204+
DocReader 服务配置了健康检查：
205+
206+
```yaml
207+
healthcheck:
208+
test: ["CMD", "grpc_health_probe", "-addr=:50051"]
209+
interval: 30s
210+
timeout: 10s
211+
retries: 3
212+
start_period: 60s
213+
```
214+
215+
可以通过以下命令检查服务状态：
216+
217+
```bash
218+
docker ps | grep docreader
219+
docker logs WeKnora-docreader
220+
```
221+
222+
## 更多信息
223+
224+
- 服务端口：50051（gRPC）
225+
- 容器名称：WeKnora-docreader
226+
- 网络：WeKnora-network
227+
- 重启策略：unless-stopped

‎docs/QA.md‎

Lines changed: 14 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ INIT_RERANK_MODEL_API_KEY=your_rerank_model_api_key
5757

5858
2. 查看主服务日志，是否有`ERROR`日志输出
5959

60-
## 4. 多模态功能显示无效的图片链接？
60+
## 4. 没有图片或者显示无效的图片链接？
6161

6262
当使用多模态功能时，如果遇到图片无法显示或显示无效链接的问题，请按照以下步骤排查：
6363

@@ -95,48 +95,32 @@ docker-compose --profile full up -d
9595

9696
**重要提示**：如果你需要从其他设备或容器访问图片，`localhost` 可能无法正常工作，需要将其替换为本机的实际 IP 地址：
9797

98-
### 5. 验证配置
9998

100-
完成以上配置后，重启相关服务：
99+
## 5. 平台兼容性说明
101100

102-
```bash
103-
docker-compose restart docreader app
104-
```
105-
106-
然后查看文档解析模块日志，确认 OCR 和 Caption 是否正确解析：
107-
108-
```bash
109-
docker-compose logs -f docreader
110-
```
101+
**重要提示**：`OCR_BACKEND=paddle` 模式在部分平台上可能无法正常运行。如果遇到 PaddleOCR 启动失败的问题，请选择以下解决方案
111102

103+
### 方案一：关闭 OCR 识别
112104

113-
## 5. docreader 服务无法启动？
105+
在 `docker-compose.yml` 文件的 `docreader` 服务中删除 `OCR_BACKEND` 配置，然后重启 docreader 服务
114106

115-
如果 docreader 服务启动失败，日志中出现类似以下信息：
116-
117-
```
118-
2026-01-12 xx:xx:xx.xxx [no-req-id] INFO __main__ | Initializing OCR engine with backend: paddle
119-
Initializing server logging
120-
```
121-
122-
这通常是因为 PaddleOCR 启动失败导致的。
107+
**注意**：设置为 `no_ocr` 后，文档解析将不会使用 OCR 功能，这可能会影响图片和扫描文档的文字识别效果。
123108

124-
### 解决方案
109+
### 方案二：使用外部 OCR 模型（推荐）
125110

126-
在 `docker-compose.yml` 文件的 `docreader` 服务中，已经配置了 `OCR_BACKEND` 环境变量：
111+
如果需要 OCR 功能，可以使用外部的视觉语言模型（VLM）来替代 PaddleOCR。在 `docker-compose.yml` 文件的 `docreader` 服务中配置：
127112

128113
```yaml
129114
environment:
130-
- OCR_BACKEND=${OCR_BACKEND:-no_ocr}
115+
- OCR_BACKEND=vlm
116+
- OCR_API_BASE_URL=${OCR_API_BASE_URL:-}
117+
- OCR_API_KEY=${OCR_API_KEY:-}
118+
- OCR_MODEL=${OCR_MODEL:-}
131119
```
132120
133-
然后重启 docreader 服务：
121+
然后重启 docreader 服务
134122
135-
```bash
136-
docker-compose restart docreader
137-
```
138-
139-
**注意**：设置为 `no_ocr` 后，文档解析将不会使用 OCR 功能，这可能会影响图片和扫描文档的文字识别效果。
123+
**优势**：使用外部 OCR 模型可以获得更好的识别效果，且不受平台限制。
140124
141125
## 6. 如何使用数据分析功能？
142126

0 commit comments

Comments
 (0)