# AI Provider 与长论文

> OpenAI、Compatible/Sub2API、400 Schema 与 524

# 20. 配置 AI Provider

进入：

```text
设置 → AI 服务 → 新增 AI 服务
```

## OpenAI Official

填写：

```text
服务名称：OpenAI Official
服务类型：OpenAI Official
API Key：你的 OpenAI API Key
Model：你的账号可用模型
启用：是
默认：按需要
```

## OpenAI Compatible / Sub2API

例如：

```text
服务名称：Sub2API
服务类型：OpenAI Compatible
Base URL：https://api.example.com/v1
API Key：sk-...
Model：中转站实际模型 ID
启用：是
默认：是
```

### Base URL 只填写 API 根路径

正确：

```text
https://api.example.com/v1
```

错误：

```text
https://api.example.com/v1/chat/completions
```

程序会自己调用 endpoint。

点击：

```text
测试连接
```

成功后再正式使用。

---


# 21. AI Compatible 最终兼容策略

历史真实错误：

```text
400 Invalid schema for response_format
Extra required key 'confidence'
```

最终版已改为：

```text
OpenAI Official
→ 官方 Structured Outputs

OpenAI Compatible
→ Chat Completions
→ JSON Object / Plain JSON fallback
→ Graduate OS 本地 JSON.parse
→ Graduate OS 本地 Zod 校验
```

因此第三方网关不需要完整实现 OpenAI strict json_schema。

`confidence` 等字段仍然保留，由服务器本地校验。

如果上线后仍看到老的：

```text
paper_analysis_text_fallback Invalid schema
```

通常说明：

```text
旧源码没有被完整覆盖
或
覆盖后没有重新 npm run build
或
PM2 仍然运行旧 .next
```

---


# 22. 长 PDF 与 524 超时

历史真实错误：

```text
status_code=524
The origin web server did not return a complete response within the 120-second Proxy Read Timeout window.
```

最终版针对 OpenAI Compatible 已加入：

- 章节优先文本整理
- 输入预算
- 更短的降级重试
- 少量分块分析
- 超时识别
- 有限重试
- 最终失败写 `FAILED`

分析过程中页面会自动轮询状态。

如果仍超时：

1. 稍后重试。
2. 检查中转站是否拥堵。
3. 先用较短 PDF 验证 Provider。
4. 查看 `/logs/error.log` 和 AI 调用记录。

不要因为第三方 524 去无限增加 Nginx 超时时间；524 是第三方上游限制。

---