Skip to content

Commit c0522b8

Browse files
BobholamovicBobholamovic
authored
[Cherry-Pick] #17329 #17367 (#17516)
* [Feat] Support `vl_rec_api_model_name` and add notes on hosted VLM services (#17367) * Add notes on hosted VLM services * Update code * Update MCP server docs * Limit lower bound of paddlex * Reset paddlex lower bound version * [Feat] Support Qianfan PP-StructureV3 MCP server (#17329) * Support Qianfan PP-StructureV3 MCP server * Bump version to 0.4.1
1 parent 75aa351 commit c0522b8

8 files changed

Lines changed: 288 additions & 29 deletions

File tree

‎docs/version3.x/deployment/mcp_server.en.md‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ This section explains how to use the PaddleOCR MCP server within Claude for Desk
146146
```json
147147
{
148148
"mcpServers": {
149-
"paddleocr-ocr": {
149+
"paddleocr": {
150150
"command": "paddleocr_mcp",
151151
"args": [],
152152
"env": {
@@ -205,7 +205,7 @@ This section explains how to use the PaddleOCR MCP server within Claude for Desk
205205

206206
4. **Restart the MCP Host**
207207

208-
Restart Claude for Desktop. The `paddleocr-ocr` tool should now be available in the application.
208+
Restart Claude for Desktop. The `paddleocr` server should now be available in the application.
209209

210210
### 2.2 MCP Host Configuration Details
211211

@@ -238,7 +238,7 @@ Configuration example:
238238
```json
239239
{
240240
"mcpServers": {
241-
"paddleocr-ocr": {
241+
"paddleocr": {
242242
"command": "paddleocr_mcp",
243243
"args": [],
244244
"env": {
@@ -262,7 +262,37 @@ Configuration example:
262262

263263
- Do not expose your access token.
264264

265-
#### Mode 3: Self-hosted Service
265+
#### Mode 3: Qianfan Platform Services
266+
267+
1. Install `paddleocr-mcp`.
268+
2. Obtain an API key by referring to the [Qianfan Platform Official Documentation](https://cloud.baidu.com/doc/qianfan-api/s/ym9chdsy5).
269+
3. Modify the `claude_desktop_config.json` file according to the configuration example below. Set `PADDLEOCR_MCP_QIANFAN_API_KEY` to your Qianfan platform API key.
270+
4. Restart the MCP host.
271+
272+
Configuration example:
273+
274+
```json
275+
{
276+
"mcpServers": {
277+
"paddleocr": {
278+
"command": "paddleocr_mcp",
279+
"args": [],
280+
"env": {
281+
"PADDLEOCR_MCP_PIPELINE": "PaddleOCR-VL",
282+
"PADDLEOCR_MCP_PPOCR_SOURCE": "qianfan",
283+
"PADDLEOCR_MCP_SERVER_URL": "https://qianfan.baidubce.com/v2/ocr",
284+
"PADDLEOCR_MCP_QIANFAN_API_KEY": "<your-api-key>"
285+
}
286+
}
287+
}
288+
}
289+
```
290+
291+
**Note**:
292+
293+
- `PADDLEOCR_MCP_PIPELINE` should be set to the pipeline name. See Section 4 for more details. The Qianfan platform service currently only supports PaddleOCR-VL and PP-StructureV3.
294+
295+
#### Mode 4: Self-hosted Service
266296

267297
1. In the environment where you need to run the PaddleOCR inference server, run the inference server as per the [PaddleOCR serving documentation](./serving.en.md).
268298
2. Install `paddleocr-mcp` where the MCP server will run.
@@ -274,7 +304,7 @@ Configuration example:
274304
```json
275305
{
276306
"mcpServers": {
277-
"paddleocr-ocr": {
307+
"paddleocr": {
278308
"command": "paddleocr_mcp",
279309
"args": [],
280310
"env": {
@@ -304,7 +334,7 @@ Currently, for the PaddleOCR official website and self-hosted modes, and (for CP
304334
```json
305335
{
306336
"mcpServers": {
307-
"paddleocr-ocr": {
337+
"paddleocr": {
308338
"command": "uvx",
309339
"args": [
310340
"--from",
@@ -326,7 +356,7 @@ Currently, for the PaddleOCR official website and self-hosted modes, and (for CP
326356
```json
327357
{
328358
"mcpServers": {
329-
"paddleocr-ocr": {
359+
"paddleocr": {
330360
"command": "uvx",
331361
"args": [
332362
"--from",

‎docs/version3.x/deployment/mcp_server.md‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ paddleocr_mcp --help
146146
```json
147147
{
148148
"mcpServers": {
149-
"paddleocr-ocr": {
149+
"paddleocr": {
150150
"command": "paddleocr_mcp",
151151
"args": [],
152152
"env": {
@@ -172,7 +172,7 @@ paddleocr_mcp --help
172172

173173
5. **重启 MCP 主机**
174174

175-
重启 Claude for Desktop。新的 `paddleocr-ocr` 工具现在应该可以在应用中使用了。
175+
重启 Claude for Desktop。新的 `paddleocr` 服务现在应该可以在应用中使用了。
176176

177177
### 2.2 MCP 主机配置说明
178178

@@ -196,7 +196,7 @@ paddleocr_mcp --help
196196
```json
197197
{
198198
"mcpServers": {
199-
"paddleocr-ocr": {
199+
"paddleocr": {
200200
"command": "paddleocr_mcp",
201201
"args": [],
202202
"env": {
@@ -253,7 +253,37 @@ paddleocr_mcp --help
253253

254254
对于文字识别以外的任务，请在 PaddleOCR 官网获取任务对应的服务基础 URL，并正确设置 `PADDLEOCR_MCP_PIPELINE` 与 `PADDLEOCR_MCP_SERVER_URL`（参数说明详见第 4 节）。
255255

256-
#### 模式三：自托管服务
256+
#### 模式三：千帆平台服务
257+
258+
1. 安装 `paddleocr-mcp`。
259+
2. 参考 [千帆平台官方文档](https://cloud.baidu.com/doc/qianfan-api/s/ym9chdsy5) 获取 API key。
260+
3. 参考下方的配置示例更改 `claude_desktop_config.json` 文件内容。将 `PADDLEOCR_MCP_QIANFAN_API_KEY` 设置为千帆平台的 API key。
261+
4. 重启 MCP 主机。
262+
263+
配置示例：
264+
265+
```json
266+
{
267+
"mcpServers": {
268+
"paddleocr": {
269+
"command": "paddleocr_mcp",
270+
"args": [],
271+
"env": {
272+
"PADDLEOCR_MCP_PIPELINE": "PaddleOCR-VL",
273+
"PADDLEOCR_MCP_PPOCR_SOURCE": "qianfan",
274+
"PADDLEOCR_MCP_SERVER_URL": "https://qianfan.baidubce.com/v2/ocr",
275+
"PADDLEOCR_MCP_QIANFAN_API_KEY": "<your-api-key>"
276+
}
277+
}
278+
}
279+
}
280+
```
281+
282+
**说明**：
283+
284+
- `PADDLEOCR_MCP_PIPELINE` 需要被设置为产线名称。详见第 4 节。千帆平台服务目前仅支持 PaddleOCR-VL 和 PP-StructureV3。
285+
286+
#### 模式四：自托管服务
257287

258288
1. 在需要运行 PaddleOCR 推理服务器的环境中，参考 [PaddleOCR 服务化部署文档](./serving.md) 运行推理服务器。
259289
2. 在需要运行 MCP 服务器的环境中安装 `paddleocr-mcp`。
@@ -265,7 +295,7 @@ paddleocr_mcp --help
265295
```json
266296
{
267297
"mcpServers": {
268-
"paddleocr-ocr": {
298+
"paddleocr": {
269299
"command": "paddleocr_mcp",
270300
"args": [],
271301
"env": {
@@ -294,7 +324,7 @@ paddleocr_mcp --help
294324
```json
295325
{
296326
"mcpServers": {
297-
"paddleocr-ocr": {
327+
"paddleocr": {
298328
"command": "uvx",
299329
"args": [
300330
"--from",
@@ -315,7 +345,7 @@ paddleocr_mcp --help
315345
```json
316346
{
317347
"mcpServers": {
318-
"paddleocr-ocr": {
348+
"paddleocr": {
319349
"command": "uvx",
320350
"args": [
321351
"--from",

‎docs/version3.x/pipeline_usage/PaddleOCR-VL.en.md‎

Lines changed: 87 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -280,7 +280,12 @@ If not set, the initialized parameter value will be used.
280280
</tr>
281281
<tr>
282282
<td><code>vl_rec_max_concurrency</code></td>
283-
<td>If the multimodal recognition model uses an inference service, this parameter is used to specify the maximum number of concurrent requests.</td>
283+
<td><b>Meaning:</b>If the multimodal recognition model uses an inference service, this parameter is used to specify the maximum number of concurrent requests.</td>
284+
<td><code>int</code></td>
285+
</tr>
286+
<tr>
287+
<td><code>vl_rec_api_model_name</code></td>
288+
<td>If the multimodal recognition model uses an inference service, this parameter is used to specify the model name of the service.</td>
284289
<td><code>str</code></td>
285290
</tr>
286291
<tr>
@@ -594,7 +599,13 @@ If not set, the initialized parameter value will be used.
594599
</tr>
595600
<tr>
596601
<td><code>vl_rec_max_concurrency</code></td>
597-
<td>If the multimodal recognition model uses an inference service, this parameter is used to specify the maximum number of concurrent requests.</td>
602+
<td><b>Meaning:</b>If the multimodal recognition model uses an inference service, this parameter is used to specify the maximum number of concurrent requests.</td>
603+
<td><code>int|None</code></td>
604+
<td><code>None</code></td>
605+
</tr>
606+
<tr>
607+
<td><code>vl_rec_api_model_name</code></td>
608+
<td>If the multimodal recognition model uses an inference service, this parameter is used to specify the model name of the service.</td>
598609
<td><code>str|None</code></td>
599610
<td><code>None</code></td>
600611
</tr>
@@ -1042,6 +1053,8 @@ There are two methods to launch the VLM inference service; choose either one:
10421053

10431054
- Method 2: Launch the service by manually installing dependencies via the PaddleOCR CLI.
10441055

1056+
In addition, cloud platforms such as [SiliconFlow](https://siliconflow.cn/) and [Novita AI](https://novita.ai/models-console/model-detail/paddlepaddle-paddleocr-vl) also provide managed services. If you choose to use such services, you can skip this section and directly read [3.2 Client Usage Methods](#32-client-usage-methods).
1057+
10451058
#### 3.1.1 Method 1: Using Docker Image
10461059

10471060
PaddleOCR provides Docker images for quickly launching vLLM or FastDeploy inference services. You can use the following commands to start the services (requires Docker version >= 19.03, a machine equipped with a GPU, and NVIDIA drivers supporting CUDA 12.6 or later):
@@ -1141,15 +1154,83 @@ After launching the VLM inference service, the client can call the service throu
11411154
Specify the backend type (`vllm-server` or `sglang-server`) using `--vl_rec_backend` and the service address using `--vl_rec_server_url`, for example:
11421155

11431156
```shell
1144-
paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server --vl_rec_server_url http://127.0.0.1:8118/v1
1157+
paddleocr doc_parser --input paddleocr_vl_demo.png --vl_rec_backend vllm-server --vl_rec_server_url http://localhost:8118/v1
1158+
```
1159+
1160+
In addition, you can specify the model name used by the service via `--vl_rec_api_model_name`, and specify the API key used for authentication via `--vl_rec_api_key`. Examples are as follows:
1161+
1162+
Using a service started with the default parameters of `vllm serve`:
1163+
1164+
```shell
1165+
paddleocr doc_parser \
1166+
--input paddleocr_vl_demo.png \
1167+
--vl_rec_backend vllm-server \
1168+
--vl_rec_server_url http://localhost:8000/v1 \
1169+
--vl_rec_api_model_name 'PaddlePaddle/PaddleOCR-VL'
1170+
```
1171+
1172+
SiliconFlow platform:
1173+
1174+
```shell
1175+
paddleocr doc_parser \
1176+
--input paddleocr_vl_demo.png \
1177+
--vl_rec_backend vllm-server \
1178+
--vl_rec_server_url https://api.siliconflow.cn/v1 \
1179+
--vl_rec_api_model_name 'PaddlePaddle/PaddleOCR-VL' \
1180+
--vl_rec_api_key xxxxxx
1181+
```
1182+
1183+
Novita AI platform:
1184+
1185+
```shell
1186+
paddleocr doc_parser \
1187+
--input paddleocr_vl_demo.png \
1188+
--vl_rec_backend vllm-server \
1189+
--vl_rec_server_url https://api.novita.ai/openai \
1190+
--vl_rec_api_model_name 'paddlepaddle/paddleocr-vl' \
1191+
--vl_rec_api_key xxxxxx
11451192
```
11461193

11471194
#### 3.2.2 Python API Invocation
11481195

1149-
Pass the `vl_rec_backend` and `vl_rec_server_url` parameters when creating a `PaddleOCRVL` object:
1196+
When creating a `PaddleOCRVL` object, pass the `vl_rec_backend` and `vl_rec_server_url` parameters to specify the backend type and the service endpoint, respectively:
1197+
1198+
```python
1199+
pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", vl_rec_server_url="http://localhost:8118/v1")
1200+
```
1201+
1202+
In addition, you can specify the model name used by the service via `vl_rec_api_model_name`, and specify the API key used for authentication via `vl_rec_api_key`.
1203+
1204+
Using a service started with the default parameters of `vllm serve`:
1205+
1206+
```python
1207+
pipeline = PaddleOCRVL(
1208+
vl_rec_backend="vllm-server",
1209+
vl_rec_server_url="http://localhost:8000/v1",
1210+
vl_rec_api_model_name="PaddlePaddle/PaddleOCR-VL",
1211+
)
1212+
```
1213+
1214+
SiliconFlow platform:
11501215

11511216
```python
1152-
pipeline = PaddleOCRVL(vl_rec_backend="vllm-server", vl_rec_server_url="http://127.0.0.1:8118/v1")
1217+
pipeline = PaddleOCRVL(
1218+
vl_rec_backend="vllm-server",
1219+
vl_rec_server_url="https://api.siliconflow.cn/v1",
1220+
vl_rec_api_model_name="PaddlePaddle/PaddleOCR-VL",
1221+
vl_rec_api_key="xxxxxx",
1222+
)
1223+
```
1224+
1225+
Novita AI platform:
1226+
1227+
```python
1228+
pipeline = PaddleOCRVL(
1229+
vl_rec_backend="vllm-server",
1230+
vl_rec_server_url="https://api.novita.ai/openai",
1231+
vl_rec_api_model_name="paddlepaddle/paddleocr-vl",
1232+
vl_rec_api_key="xxxxxx",
1233+
)
11531234
```
11541235

11551236
### 3.3 Performance Tuning
@@ -2270,7 +2351,7 @@ VLRecognition:
22702351
...
22712352
genai_config:
22722353
backend: vllm-server
2273-
server_url: http://127.0.0.1:8118/v1
2354+
server_url: http://localhost:8118/v1
22742355
```
22752356

22762357
The Docker Compose solution already uses an acceleration framework by default.

0 commit comments

Comments
 (0)