大模型PHP SDK使用教程：从安装到调用避坑

在PHP项目里接入大模型，最省事的方式是使用官方或社区维护的SDK，通过Composer安装后直接调用封装好的方法。
本文以常见的“对话补全”接口为例，讲清楚从零安装、配置密钥、发起请求到验证结果的完整流程，并给出超时、SSL、流式输出等高频问题的处理办法。
适用于PHP 7.4及以上、有Composer基础的项目；
不同厂商的SDK命名和参数会有差异，请以你实际安装的包文档为准。

环境确认与依赖安装

动手前先确认PHP版本和Composer可用。
在项目根目录执行：

php -v
composer --version

预期结果是PHP版本不低于7.4，Composer能正常打印版本号。
如果提示命令不存在，需要先安装PHP CLI和Composer。

接着安装SDK。
以常见的OpenAI风格SDK为例（包名以Packagist实际为准）：

composer require openai-php/client

安装完成后检查composer.json的require段是否出现该包，并确认vendor/autoload.php存在。
这一步是后续所有调用的前提。

密钥配置与第一个请求

不要把API密钥硬编码在业务代码里。
推荐在项目根目录创建.env文件，写入：

OPENAI_API_KEY=你的密钥
OPENAI_BASE_URL=https://api.example.com/v1

BASE_URL用于指定服务地址，使用代理或兼容接口时尤其重要。
然后在入口文件加载自动加载和密钥：

require __DIR__ . '/vendor/autoload.php';

$client = OpenAI::factory()
    ->withApiKey(getenv('OPENAI_API_KEY'))
    ->withBaseUri(getenv('OPENAI_BASE_URL'))
    ->make();

$response = $client->chat()->create([
    'model' => 'gpt-3.5-turbo',
    'messages' => [
        ['role' => 'user', 'content' => '用一句话解释什么是PHP'],
    ],
]);

echo $response->choices[0]->message->content;

运行php test.php，如果终端打印出模型回复，说明密钥和网络都正常。
若报401，优先检查密钥是否复制完整、是否有多余空格；
若报404，检查BASE_URL是否包含/v1后缀。

流式输出与超时控制

需要打字机效果时，用流式请求。
SDK通常提供createStreamed方法：

$stream = $client->chat()->createStreamed([
    'model' => 'gpt-3.5-turbo',
    'messages' => [['role' => 'user', 'content' => '写一段PHP数组遍历示例']],
]);

foreach ($stream as $chunk) {
    echo $chunk->choices[0]->delta->content ?? '';
    ob_flush();
    flush();
}

流式场景下，PHP的max_execution_time和网关超时都可能中断连接。
建议在脚本开头设置set_time_limit(0)（仅限命令行或可控环境），并确认Nginx的fastcgi_read_timeout足够大。
生产环境更推荐把流式请求放在异步任务或SSE接口中处理。

常见报错与处理思路

• cURL error 60 SSL证书问题：更新系统的CA证书包，或在php.ini中正确配置curl.cainfo路径。不要图省事关掉SSL验证。
• 请求超时：先调大SDK客户端超时参数（如withHttpClient自定义超时），再排查服务器到目标API的网络连通性，可用curl -v测试同一地址。
• 返回内容为空：检查messages格式是否为数组、role和content字段是否拼写正确；部分模型要求首条消息为system角色。
• 密钥泄露风险：.env文件必须加入.gitignore，不要在日志中打印完整请求头。

结果验证与上线前检查

完成调用后，用三个动作确认可用性：第一，连续发起两次普通请求，确认都能返回非空内容；
第二，用错误密钥请求一次，确认程序能捕获异常而不是白屏；
第三，检查错误日志目录，确认没有残留的密钥明文。
上线前把BASE_URL、模型名称、超时时间抽到配置文件，避免散落在业务代码中。

如果你在安装或调用过程中遇到其他报错，优先核对SDK版本与接口文档的对应关系，再按报错关键词检索社区Issue。
大模型PHP SDK使用的核心就是：依赖装对、密钥配好、请求参数对齐、异常有兜底。