LayBot / AI-SDK · PHP

灵语智教 · 多模型厂商与实时语音能力聚合 SDK
Ark · DeepSeek · OpenAI-Compatible · Responses · TTS · ASR · Webman Async

Chat · Responses · SSE · Tool Calls · Files · TTS · AUC · SAUC · WebSocket

Powered by LayBot LingTeach AI · Laybot 现代 MPA 工程平台

laybot/ai-sdk 是面向 PHP 8.1+ 的多供应商 AI 与语音协议 SDK。
它在 laybot/request-sdk 之上统一 Chat、Responses、流式文本、Tool Call、Usage、Files、TTS、ASR 和供应商异常。

1. 项目简介

在企业 AI 项目中，接入大模型通常不只是发送一次 HTTP 请求。

实际系统还需要处理：

• 多供应商模型切换；
• 同步与异步调用；
• SSE 增量文本；
• Reasoning 输出；
• Tool Call 参数归并；
• Responses API；
• 图片、PDF 和 Files API；
• Token Usage；
• Request ID 和供应商日志 ID；
• HTTP Chunked、NDJSON 和二进制协议；
• 实时 TTS 和 ASR；
• WebSocket Session 状态机；
• 连接、请求和流空闲超时；
• 取消、背压和资源释放；
• 供应商错误码和重复计费风险；
• Webman 常驻进程中的租户配置隔离。

laybot/ai-sdk 将这些能力收敛为统一的 PHP API：

它解决的不是单纯的“调用一个模型”，而是：

如何在 PHP 企业项目中，以可维护、可观测、可取消、可扩展的方式统一接入模型和实时语音供应商。

2. LayBot 体系

本 SDK 脱胎于：

• LayBot 灵语智教 AI 平台
• Laybot 现代 MPA 工程平台

LayBot 系列组件包括：

推荐分层：

3. 核心能力

3.1 大模型

• OpenAI-Compatible Chat Completions
• 非流式 Chat
• 同步 SSE Chat
• Workerman 异步 SSE Chat
• 正文增量
• Reasoning 增量
• 加密 Reasoning 元数据
• Tool Call 增量与归并
• Usage 统一映射
• Finish Reason
• Request ID
• Responses API
• Responses SSE
• 图片、PDF 和文件输入
• Files 上传、查询、列表、下载与删除
• Embeddings、Images、Audio、Batches、Fine-tuning 资源入口
• 模型能力注册表

3.2 火山语音

• AUC 文件语音识别
• AUC Submit / Query
• SAUC Async 实时识别
• SAUC Nostream 流式输入识别
• HTTP SSE TTS
• HTTP Chunked / JSON Lines TTS
• 双向 WebSocket TTS
• 连续文本 TaskRequest
• PCM、MP3 等音频输出参数
• 声音复刻音色状态查询
• Sentence 事件
• TTS Usage
• WebSocket 背压、取消和正常关闭

3.3 工程能力

• PHP 8.1+ 强类型 DTO
• 同步和异步 API 语义分离
• 生成式请求默认不透明重试
• 供应商配置不可变覆盖
• 多租户 API Key 隔离
• 连接超时、请求超时和流空闲超时
• Header 安全合并
• API Key 日志脱敏
• 供应商异常统一映射
• 部分输出与可能计费标记
• Webman/Workerman 常驻进程适配
• PHPUnit 和 PHPStan 验证

4. 当前供应商状态

4.1 已通过真实账号验收

4.2 已实现但尚未完成真实账号验收

“协议已实现”不等同于“已完成目标账号生产验收”。
正式项目应依据自身模型、区域、配额和供应商版本执行集成测试。

5. 框架支持

SDK 不会根据环境自动改变方法语义：

6. 运行要求

基础要求：

异步 HTTP、SSE、TTS 和 ASR 需要底层 Workerman 事件循环支持。

推荐生产环境：

7. 安装

本地开发：

8. 配置

8.1 创建统一 AiClient

8.2 Provider 配置项

支持通过别名配置同一协议：

9. Chat 快速开始

9.1 Ark 非流式 Chat

9.2 DeepSeek 非流式 Chat

10. 统一 completions() 入口

completions() 根据请求中的 stream 决定返回类型：

返回类型：

11. 同步流式 Chat

流式结果包含：

12. Webman 异步流式 Chat

在 Webman/Workerman 已运行的 Worker 中：

取消：

在已经运行的 Webman Worker 中不要再次调用：

13. ChatRequest DTO

规则：

调用方可以动态传入任何运行时模型和消息，SDK 不会写死模型。

14. Tool Calls

OpenAI-Compatible 请求：

流式 Tool Call 会按 choice_index 和 index 归并。

统一结果当前只支持单候选：

15. Ark Responses API

15.1 文本

completed 只在供应商返回：

时为 true。

如果供应商返回：

SDK 不会将其伪装成成功。

15.2 公网图片 URL

15.3 公网 PDF URL

15.4 上传文件并使用 file_id

文件上传后可能暂时处于：

业务项目应轮询文件状态，不能对所有错误盲目重试。

15.5 Responses SSE

异步：

16. 火山语音配置

火山语音 API Key 与 Ark API Key 是不同凭证。

所有凭证都只能保存在服务端，不要放入：

• 浏览器 JavaScript；
• uni-app 前端源码；
• Electron 渲染进程；
• Git 仓库；
• App 安装包；
• 可公开下载的配置文件。

17. HTTP SSE TTS

结果包含：

大音频不要长期拼接在内存中，应在 AUDIO_CHUNK 回调中持续写入临时文件。

18. HTTP Chunked TTS

HTTP Chunked 使用 JSON Lines 解析。

由于不同火山产品和账号可能返回不同外层结构，正式上线前必须使用目标账号执行协议验收。

19. 查询已有复刻音色

当前 SDK 支持：

当前未提供完整的：

20. 双向 WebSocket TTS

双向 TTS 需要 Workerman 事件循环。

连接状态：

Session 状态：

同一连接同时只允许一个活动 Session。

只有收到当前 Session 的终态后，才能创建下一个 Session。

21. Ark 流式文本接入实时 TTS

推荐链路：

注意：

• 只发送最终正文 TEXT_DELTA；
• 不发送 Reasoning；
• 不重复发送 Delta；
• 不为每个 Delta 新建 TTS Session；
• 一条 AI 回复使用一个 TTS Session；
• AI 失败时取消 TTS Session；
• AI 完成后调用 TTS Session finish()；
• 等 TTS SessionFinished 后再结束 Connection。

22. AUC 文件语音识别

上述轮询示例适用于 CLI 或专用任务 Worker。

在 Webman WebSocket Worker 中，不要使用 usleep() 阻塞事件循环，应使用：

或将 AUC 轮询放入独立任务进程。

23. SAUC 实时 ASR

SAUC 使用双向 WebSocket 上传音频。

收到 onReady() 后发送音频：

或者：

last=true 时 SDK 会发送火山协议要求的最后一个负序号音频包。

24. AUC 与 SAUC 的选择

一期业务可以采用：

实时增强：

如果同时执行 AUC 和 SAUC，应评估双份识别费用。

25. 超时配置

支持：

Chat 流推荐：

Ark PDF/Files 推荐：

实时语音推荐：

request_timeout=0 表示不限制流总持续时间，但仍受 idle_timeout 保护。

26. Retry 与重复计费

生成式请求默认：

这是为了避免：

• Chat 重复生成；
• Responses 重复计费；
• TTS 重复合成和播放；
• AUC 重复创建任务；
• 文件重复上传；
• Tool Call 重复执行。

只有明确幂等的查询才应启用重试：

如果已经收到部分文本或音频，不应自动重新执行完整生成请求。

ProviderException 会提供：

27. 配置覆盖与多租户

27.1 单次网络覆盖

27.2 单次 Endpoint 覆盖

Endpoint 应放在调用选项，不是模型请求 Body：

27.3 多租户 API Key

存在实例级覆盖时，AiClient 不会缓存该 ProviderClient，防止租户 Key、Base URI 和 Header 污染其他调用。

28. 常驻进程与并发建议

AiClient 可以在单个 Webman Worker 生命周期内复用：

以下对象必须按请求或会话创建：

不要：

• 在不同用户间共享同一个可变 Listener；
• 将 Session 保存为全局静态变量；
• 在多个 Worker 进程间传递连接对象；
• 在 WebSocket Worker 中执行长时间同步请求；
• 在回调内执行大量 CPU 密集任务；
• 忽略 onBufferFull()；
• 将音频 Base64 放入普通 JSON WebSocket。

服务端向 App 转发实时音频时推荐：

29. 异常体系

基础异常：

示例：

30. 日志与敏感信息

SDK 默认注册以下敏感 Header：

自定义：

生产环境不要记录：

• 完整 Prompt；
• 用户心理咨询内容；
• 音频二进制；
• Base64 音频；
• 文件签名 URL；
• API Key；
• 原始身份证明；
• 未脱敏的模型响应。

31. 模型能力注册

未知模型能力默认不会被武断阻断：

项目可以注册能力：

能力状态：

unknown 默认不阻断新模型。

32. LayBot 灵语智教平台能力

通过 LayBot Vendor 可以访问平台能力：

Chat：

平台资源入口：

教育扩展 API 包括：

具体可用模型、计费、端点和合规能力以：

• LayBot 灵语智教官网
• 实际控制台
• 对应服务协议

为准。

33. 旗舰教育模型示例

模型名称仅作为 LayBot 平台产品示例。
实际开放范围、价格和能力以控制台为准。

34. 与 Laybot MPA 前端集成

本项目是服务端 PHP SDK，不应将供应商 API Key 写入前端组件。

推荐：

正确链路：

禁止：

Laybot MPA/SPA 前端框架相关信息：

• 官网：https://www.laybot.cn
• 发明专利申请号：2025108367676

35. 安全与合规边界

SDK 提供：

• 服务端凭证管理入口；
• Header 脱敏；
• TLS 验证；
• 请求大小限制；
• 异常边界；
• 请求 ID；
• 重试安全默认值；
• 多租户配置隔离。

SDK 本身不自动完成：

• GDPR 法律合规；
• K12 内容审核；
• 用户授权；
• 数据保留策略；
• 医疗或心理咨询安全审查；
• 供应商账单结算；
• 敏感词业务规则；
• 内容版权审核。

这些能力应由：

共同完成。

36. 当前限制

当前 2.x 的明确边界：

• 不管理业务数据库；
• 不管理用户额度；
• 不负责 OSS；
• 不保存聊天消息；
• 不负责浏览器 CORS；
• 不向 App 签发火山临时 Token；
• 不提供声音复刻训练完整生命周期；
• 不自动恢复中断的 WebSocket Session；
• 不对生成式请求自动重试；
• 不支持同一统一结果中的多候选；
• 异步 API 依赖 Workerman 事件循环；
• 暂无 Swoole、Amp、ReactPHP 原生 Transport；
• 供应商未公开的私有鉴权协议不会在 SDK 中猜测实现。

37. 测试

37.1 静态检查与单元测试

当前验收基线：

37.2 小毅 AI 集成测试

当前验收基线：

已连续执行三轮通过。

37.3 全部集成测试

38. 生产发布检查

检查敏感文件：

检查 Worker 源码目录污染：

发布前清理：

真实 API Key 必须保存在本地 .env 或密钥管理系统中，不能进入版本库。

39. Webman 生产建议

普通短请求

可以使用同步 API：

长时间 Chat、Responses、实时 TTS/ASR

优先使用异步 API：

进程隔离

推荐：

不要让一个 Worker 同时承担：

• 大文件解析；
• CPU 密集 Embedding；
• 大量实时音频连接；
• 阻塞式模型请求；
• 用户 WebSocket 心跳。

40. 路线图

• 更多供应商真实账号矩阵；
• OpenAI、Gemini、Anthropic 完整集成验收；
• 火山 HTTP Chunked TTS 专项验收；
• 声音复刻训练管理；
• 更多语音格式和字幕 DTO；
• WebSocket 故障注入测试；
• 异步并发压力测试；
• Webman Service Provider；
• Laravel、ThinkPHP、Symfony 集成示例；
• 指标和 OpenTelemetry；
• 更多供应商 Embedding 与 Rerank；
• PHP 8.1～8.4 CI 矩阵。

41. 贡献指南

提交代码前必须确保：

欢迎提交 Issue 和 Pull Request。

42. LayBot 系列项目

LayBot 专注于现代 Web 工程、教育智能、知识管理和 AI 基础设施。

• LayBot 灵语智教 AI
• Laybot 现代 MPA 工程平台
• laybot/request-sdk
• laybot/ai-sdk
• laybot/storage-sdk

如果本项目对你的 PHP AI 工程有帮助，欢迎 Star、反馈和参与建设。

43. License、NOTICE 与署名

本项目采用 Apache License 2.0 开源协议。

Apache License 2.0 允许：

• 商业使用；
• 修改；
• 分发；
• 专利授权范围内使用；
• 在遵守许可证的情况下闭源集成。

分发本项目或其衍生版本时，应按照 Apache License 2.0 的要求：

• 保留 LICENSE；
• 保留适用的版权声明；
• 标明修改内容；
• 如果发行包包含 NOTICE，保留其中适用的归属说明。

LayBot、Laybot、灵语智教、LayBot LingTeach AI 及相关标识属于其权利人。Apache License 2.0 不授予商标使用权。

技术与产品信息：

• LayBot 灵语智教：https://ai.laybot.cn
• Laybot MPA：https://www.laybot.cn

LayBot · 灵语智教
稳定连接模型，让 PHP 专注业务。