42 lines
1.3 KiB
Markdown
42 lines
1.3 KiB
Markdown
---
|
||
name: ocr_client_initialization
|
||
description: 当 OCRClient/OpenAI 初始化报错、WebTerminal 创建失败、或升级 openai 包时，应该索引本记忆
|
||
---
|
||
|
||
# OCRClient 初始化与 OpenAI 包兼容性
|
||
|
||
## 问题
|
||
|
||
`modules/ocr_client.py` 在 `__init__` 中直接创建 `OpenAI(api_key=OCR_API_KEY)`。
|
||
|
||
- `openai` 包较新版本（>= 2.40）在 `api_key` 为空时会抛出 `openai.OpenAIError: Missing credentials`
|
||
- 服务器 settings.json 通常未配置 `OCR_API_KEY`
|
||
- 这会导致 `WebTerminal`/`MainTerminal` 初始化失败，所有依赖 terminal 的 API 都返回 500
|
||
|
||
## 修复
|
||
|
||
在 `OCRClient.__init__` 中，仅在 `OCR_API_KEY` 存在时才创建 `OpenAI` 客户端：
|
||
|
||
```python
|
||
self.client = None
|
||
if OCR_API_KEY:
|
||
self.client = OpenAI(
|
||
api_key=OCR_API_KEY,
|
||
base_url=base_url or None,
|
||
http_client=self.http_client,
|
||
)
|
||
```
|
||
|
||
在 `vlm_analyze` 中同时检查 `self.client`：
|
||
|
||
```python
|
||
if not self.client or not OCR_API_KEY or not OCR_API_BASE_URL or not self.model:
|
||
return {"success": False, "error": "VLM 配置缺失，请设置 OCR_API_BASE_URL / OCR_API_KEY / OCR_MODEL_ID", "warnings": warnings}
|
||
```
|
||
|
||
## 教训
|
||
|
||
- 升级依赖包后要检查破坏性变更
|
||
- 可选功能（OCR/VLM）的客户端初始化不应阻塞主终端启动
|
||
- 服务器环境缺少某个 API key 时，应优雅降级而不是直接崩溃
|