[usage] add self-host detailed README - #189
Conversation
Signed-off-by: JaredforReal <w13431838023@gmail.com>
Signed-off-by: JaredforReal <w13431838023@gmail.com>
There was a problem hiding this comment.
Pull request overview
Adds documentation for a “split deployment” mode where a GPU-hosted glmocr Flask server runs the full OCR pipeline and GPU-less clients call it via the MaaS-compatible protocol.
Changes:
- Document a new “SDK Server + Client (GPU-less Client)” deployment option in both English and Chinese READMEs.
- Add a new detailed guide at
examples/self-host/README.mddescribing server/client setup and protocol compatibility.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| README.md | Adds Option 4 pointing users to the self-host server+client guide and a client-side pipeline.maas config example. |
| README_zh.md | Chinese equivalent of the new Option 4 documentation and link to the guide. |
| examples/self-host/README.md | New end-to-end self-host guide (architecture, server install/run, client config, protocol/response fields). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Deploy the SDK Server on a GPU machine, then use any machine as a client — no GPU needed on the client side. The client connects via the MaaS-compatible protocol, pointing `api_url` at your self-hosted server. | ||
|
|
||
| ```yaml | ||
| # Client config.yaml | ||
| pipeline: | ||
| maas: | ||
| enabled: true | ||
| api_url: http://<SERVER_IP>:5002/glmocr/parse | ||
| api_key: any-string # self-hosted server does not validate keys | ||
| verify_ssl: false |
There was a problem hiding this comment.
The snippet explicitly notes the self-hosted server does not validate API keys, which means the endpoint is unauthenticated by default. Please add a clear warning not to expose this server publicly, and recommend putting it behind network controls (firewall/VPC) and/or a reverse proxy providing TLS + auth if used outside a trusted network.
| #### Option 4: SDK Server + Client (GPU-less Client) | ||
|
|
||
| Deploy the SDK Server on a GPU machine, then use any machine as a client — no GPU needed on the client side. The client connects via the MaaS-compatible protocol, pointing `api_url` at your self-hosted server. |
There was a problem hiding this comment.
PR description currently contains a generic contribution guide template and doesn’t describe the self-hosted README additions. Please update the PR description to match the actual change (adding a self-hosted SDK server/client guide) so reviewers and release notes consumers have accurate context.
| 在 GPU 机器上部署 SDK Server，其他机器作为 Client 通过网络调用——Client 端无需 GPU。Client 通过 MaaS 兼容协议连接，将 `api_url` 指向自建 Server 即可。 | ||
|
|
||
| ```yaml | ||
| # Client 端 config.yaml | ||
| pipeline: | ||
| maas: | ||
| enabled: true | ||
| api_url: http://<SERVER_IP>:5002/glmocr/parse | ||
| api_key: any-string # 自建 Server 不校验 API key | ||
| verify_ssl: false |
There was a problem hiding this comment.
这里提到自建 Server 不校验 API key，意味着该服务默认无鉴权。建议补充明确的安全提示：不要将该服务直接暴露到公网；如需跨网络使用，请通过防火墙/VPC 或反向代理提供 TLS 与鉴权（例如 Basic Auth / Token / mTLS）。
| # CLI | ||
| glmocr parse document.png --config config.yaml | ||
|
|
||
| # Or set via environment variable |
There was a problem hiding this comment.
The “Or set via environment variable” example only sets ZHIPU_API_KEY and then runs glmocr parse without --config. Without also overriding the MaaS api_url (e.g., via GLMOCR_API_URL or a config file), the CLI will use the packaged default cloud endpoint instead of the self-hosted server. Update this section to either keep using --config config.yaml or show the necessary env vars to point pipeline.maas.api_url at the self-hosted server.
| # Or set via environment variable | |
| # Or set via environment variables | |
| export GLMOCR_API_URL=http://<SERVER_IP>:5002/glmocr/parse |
| enabled: true | ||
| api_url: http://<SERVER_IP>:<SERVER_PORT>/glmocr/parse | ||
| api_key: any-string # Self-hosted server does not validate API keys | ||
| verify_ssl: false # Internal networks typically lack HTTPS |
There was a problem hiding this comment.
verify_ssl: false disables TLS certificate verification when using HTTPS. Consider rewording the comment to clarify it’s only needed for self-signed/internal HTTPS; if you’re using plain http:// it has no effect, and if you’re using proper HTTPS it should remain true.
| verify_ssl: false # Internal networks typically lack HTTPS | |
| verify_ssl: false # Only relevant for https:// URLs; no effect with http://. Use false only for self-signed/internal HTTPS, otherwise keep true. |
| api_key: any-string # Self-hosted server does not validate API keys | ||
| verify_ssl: false # Internal networks typically lack HTTPS | ||
| ``` |
There was a problem hiding this comment.
This guide notes the server doesn’t validate API keys, but it should also include an explicit warning about the security implications (no auth by default) and recommend running it only on trusted networks or behind a reverse proxy with TLS/auth when used beyond localhost.
Contribution Guide
We welcome your contributions to this repository. To ensure elegant code style and better code quality, we have prepared
the following contribution guidelines.
What We Accept
follows the coding standards below.
your code strictly follows the coding standards below.
Code Style Guide
Good code style is an art. We have prepared a
pre-commithook to enforce consistent codeformatting across the project. You can clean up your code following the steps below:
If your code complies with the standards, you should not see any errors.
Naming Conventions
a,b,c.