PHP集成Ollama本地大模型：ollama-php客户端SDK实战指南

1. 项目概述一个为PHP开发者准备的Ollama桥梁如果你是一个PHP开发者最近又被大语言模型LLM的各种应用撩得心痒痒想在自己的PHP项目里快速集成一个本地运行的、可控的私有模型那么你很可能已经听说过Ollama。Ollama确实是个神器它让在本地拉取和运行如Llama 2、Mistral、CodeLlama等开源模型变得像docker run一样简单。但问题来了Ollama提供的原生接口是RESTful API而我们熟悉的PHP生态里直接去curl这些API虽然可行但每次都要处理HTTP客户端、JSON编解码、错误处理代码会显得很啰嗦也不够优雅。这正是ArdaGnsrn/ollama-php这个项目出现的意义。简单说它是一个专门为PHP打造的Ollama客户端SDK。它的目标不是去重新发明轮子而是为你造好一个称手的方向盘和变速箱让你能以一种更符合PHP开发者习惯的方式——面向对象、方法链式调用——去和本地的Ollama服务进行交互。你可以把它想象成Guzzle之于HTTP请求或者Laravel Eloquent之于数据库操作它封装了底层的通信细节暴露出一套简洁、直观的API。这个项目解决了几个核心痛点第一是标准化它定义了与Ollama API交互的通用接口避免了每个项目自己写一套参差不齐的封装第二是便捷性生成文本、对话、管理模型等常见操作都被抽象成了简单的方法调用第三是可集成性它可以轻松融入现有的PHP框架如Laravel、Symfony通过服务容器进行依赖注入和管理。对于想要快速构建基于本地大模型的智能问答、内容生成、代码辅助等功能的PHP应用来说这个库是一个高效的起点。2. 核心功能与设计哲学解析2.1 功能全景不止于“发送一个提示词”初看ollama-php你可能会觉得它就是一个简单的API包装器。但深入其设计你会发现它覆盖了Ollama官方API的大部分核心端点并在此基础上做了符合PHP生态的增强。核心模型操作这是基础中的基础。库提供了完整了模型生命周期管理方法包括pull拉取远程模型到本地、list列出本地可用模型、show查看模型详细信息如参数大小、模板以及copy和delete。例如你想在代码中动态检查是否已有所需模型无需执行系统命令直接调用$ollama-list()即可得到一个结构化的模型列表数组。文本生成与对话这是使用频率最高的部分。generate方法用于单次文本补全你只需提供模型名和提示词prompt。而chat方法则更强大它用于多轮对话。这里的设计亮点在于它对“消息”的抽象。它允许你构建一个消息数组每条消息都有role角色如user,assistant,system和content内容。这完美契合了现代LLM对话的上下文管理范式让你能轻松实现带历史记录的连续对话。高级生成参数透传Ollama的API支持丰富的生成参数来控制输出如temperature温度控制随机性、top_p核采样、num_predict最大生成长度等。ollama-php没有将这些参数隐藏而是通过options数组让你可以完全透传。这意味着你可以进行精细化的生成控制比如写创意文案时提高temperature写技术文档时降低它。流式响应支持Streaming这是处理长文本生成时提升用户体验的关键。如果让用户等待模型完全生成一大段文字再返回体验会很差。ollama-php支持流式响应当你在调用generate或chat时设置stream为true返回的将不是一个最终的响应对象而是一个可迭代的生成器Generator。你可以实时地获取到模型生成的一个个词元token并立即推送到前端如通过Server-Sent Events实现打字机式的输出效果。这个功能对于构建交互式应用至关重要。设计哲学简洁、明确、可测试。库的接口设计力求直观方法名即功能。同时它通过依赖注入DI将HTTP客户端抽象出来通常使用PSR-18兼容的客户端如Guzzle这使得单元测试变得非常容易——你可以轻松地模拟MockHTTP响应来测试你的业务逻辑而不需要启动真实的Ollama服务。2.2 与原生API调用和Python库的对比为了更清楚它的价值我们做个简单对比。原生cURL调用$ch curl_init(http://localhost:11434/api/generate); curl_setopt_array($ch, [ CURLOPT_POST true, CURLOPT_RETURNTRANSFER true, CURLOPT_HTTPHEADER [Content-Type: application/json], CURLOPT_POSTFIELDS json_encode([ model llama2, prompt 你好请介绍一下PHP。, stream false ]) ]); $response curl_exec($ch); $httpCode curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($httpCode ! 200) { throw new Exception(API请求失败); } $data json_decode($response, true); $answer $data[response] ?? 无响应;这段代码冗长包含了大量样板代码初始化、设置、错误处理、解析并且JSON结构需要手动维护。使用ollama-php$response $ollama-generate( model: llama2, prompt: 你好请介绍一下PHP。 ); $answer $response-response;代码清晰、简洁所有底层细节被封装。错误处理也会以异常的形式抛出如连接失败、模型不存在更符合现代PHP的错误处理习惯。与Python生态对比Python有官方的ollamaPython库功能完善。ollama-php可以看作是其在PHP世界的对等物。它的存在让PHP开发者无需羡慕Python生态的便利性在自己的技术栈内也能获得同等流畅的开发体验。这对于那些核心业务用PHP编写但又需要引入AI能力的团队来说减少了技术栈切换的复杂度。3. 环境准备与安装部署详解3.1 前置条件Ollama服务是基石在使用ollama-php之前有一个绝对的前提你的运行环境本地开发机或服务器上必须已经安装并运行着Ollama服务。这个库只是一个客户端它需要连接到一个Ollama服务实例。安装Ollama访问Ollama官网根据你的操作系统macOS, Linux, Windows下载安装包。安装过程通常很简单。安装完成后Ollama服务会自动在后台运行并监听11434端口。你可以通过在终端运行ollama run llama2来测试是否安装成功这会拉取并运行Llama 2模型首次需要下载时间较长。关键验证确保你能通过http://localhost:11434或你的服务器IP:11434访问到Ollama服务。一个简单的验证方法是打开浏览器访问http://localhost:11434/api/tags应该会返回一个JSON列出你本地已有的模型。注意在生产环境部署时如果Ollama服务运行在另一台机器你需要确保网络连通并且可能需要考虑安全配置如防火墙规则、是否暴露公网等。ollama-php客户端需要配置正确的Ollama服务基础URL。3.2. 安装ollama-php客户端库安装ollama-php本身非常标准通过Composer完成。它需要PHP 8.1或更高版本这是为了利用新的语言特性如枚举、只读属性等来构建更健壮的API。基础安装 在你的项目根目录下执行composer require ardagnsrn/ollama-phpComposer会自动处理依赖主要是某个PSR-18兼容的HTTP客户端如果你项目里还没有的话Composer会建议你安装一个比如guzzlehttp/guzzle。在框架中集成Laravel由于它使用了Laravel的自动包发现Auto Discovery安装后通常无需额外配置。你可以通过app(Ollama::class)来从服务容器中获取实例。为了更好地管理你可能会在AppServiceProvider的register方法中绑定一个单例并配置Ollama服务的地址如果不是默认的localhost。// 在 AppServiceProvider 中 $this-app-singleton(Ollama::class, function ($app) { return new Ollama( client: new Client(), // Guzzle HTTP Client baseUrl: http://localhost:11434 // 生产环境可配置为环境变量 ); });Symfony同样可以通过Composer安装然后在你的服务配置文件services.yaml中定义服务。services: ArdaGnsrn\Ollama\Ollama: arguments: $baseUrl: %env(OLLAMA_BASE_URL)%纯PHP项目直接在使用的地方初始化即可。require vendor/autoload.php; use ArdaGnsrn\Ollama\Ollama; use GuzzleHttp\Client; $httpClient new Client(); $ollama new Ollama(client: $httpClient, baseUrl: http://localhost:11434);配置要点最重要的配置项是baseUrl。在Docker化部署或微服务架构中Ollama可能运行在独立的容器或主机上你需要将其指向正确的地址例如http://ollama-server:11434。4. 核心API使用实战与代码剖析4.1 初始化与基础生成你的第一个AI对话让我们从最基础的文本生成开始。假设我们想用llama2模型生成一段关于PHP的简介。use ArdaGnsrn\Ollama\Ollama; use GuzzleHttp\Client; // 1. 初始化客户端 $ollama new Ollama( client: new Client([timeout 60.0]), // 设置超时生成文本可能较久 baseUrl: http://localhost:11434 ); try { // 2. 发起生成请求 $response $ollama-generate( model: llama2, // 指定模型 prompt: 用简短的一段话介绍PHP语言的核心特点。, // 提示词 options: [ // 可选参数 temperature 0.7, // 创造性中等 num_predict 150, // 最大生成约150个token ] ); // 3. 处理响应 echo 模型回复 . $response-response . PHP_EOL; echo 本次生成消耗了 {$response-eval_count} 个token耗时 {$response-total_duration} 纳秒。 . PHP_EOL; } catch (\ArdaGnsrn\Ollama\Exceptions\OllamaClientException $e) { // 处理客户端异常如网络错误、模型不存在 echo 请求出错: . $e-getMessage(); } catch (\Exception $e) { // 处理其他异常 echo 发生错误: . $e-getMessage(); }代码解读与注意事项超时设置num_predict设置为150时生成时间可能从几百毫秒到几秒不等。务必为HTTP客户端设置合理的超时如30-60秒避免请求在长时间生成时被意外中断。响应对象$response是一个结构化的对象除了核心的response文本内容还包含丰富的元数据如eval_count本次评估的token数、total_duration总耗时等。这些数据对于监控和优化很有用比如计算每个token的平均生成时间。错误处理库会抛出特定的OllamaClientException异常它可能包含Ollama服务返回的错误信息如model llama2 not found。良好的异常捕获能让你快速定位问题是出在客户端、网络还是服务端。4.2 流式生成实现“打字机”效果对于需要长时间生成或追求实时交互体验的场景流式响应是必选项。$stream $ollama-generate( model: llama2, prompt: 写一个关于人工智能的短故事开头是在未来的某个实验室里, stream: true, // 启用流式 options: [temperature 0.9] // 提高温度让故事更有创意 ); foreach ($stream as $chunk) { // $chunk 是一个响应块对象 if (!empty($chunk-response)) { // 实时输出生成的文本片段 echo $chunk-response; flush(); // 立即刷新输出缓冲区关键 } // 你也可以实时获取到当前的生成进度信息 // echo 已生成: {$chunk-eval_count} tokens\n; }核心机制与实战技巧生成器Generator当streamtrue时方法返回的是一个生成器而不是一个完整的响应对象。每次迭代foreach循环获取到的$chunk是模型刚刚生成的一小段文本可能是一个词或一个子词。flush()的重要性在CLI脚本中echo后通常会自动输出。但在Web环境中例如通过API响应输出会被缓冲。必须在使用echo后立即调用flush()和ob_flush()才能将数据立即推送到浏览器。这是实现Web端打字机效果的关键。前端配合前端通常使用EventSourceServer-Sent Events来接收这种流式数据。后端PHP脚本需要设置正确的HTTP头(Content-Type: text/event-stream)并确保在循环中按照SSE格式data: {...}\n\n输出数据。资源管理流式请求会保持一个长时间的HTTP连接。需要确保Web服务器如Nginx、Apache和PHP的配置允许长连接和足够的执行时间max_execution_time。4.3 对话模式管理多轮上下文对话模式更贴近实际应用它允许你传递一个消息历史数组。// 定义系统指令设定AI的角色和行为 $systemMessage [ role system, content 你是一个乐于助人的编程助手擅长PHP和Web开发。回答要简洁专业。 ]; // 初始化对话历史 $messages [$systemMessage]; // 第一轮用户提问 $messages[] [role user, content 如何在Laravel中定义一个资源控制器]; $response1 $ollama-chat(model: llama2, messages: $messages); $assistantReply $response1-message[content]; $messages[] [role assistant, content $assistantReply]; echo 助手: $assistantReply . PHP_EOL; // 第二轮基于历史上下文提问 $messages[] [role user, content 那如果我想只生成其中index和show方法的路由呢]; $response2 $ollama-chat(model: llama2, messages: $messages); echo 助手后续: . $response2-message[content] . PHP_EOL;上下文管理策略系统消息System用于在对话开始前给模型设定一个“人设”或全局指令这对稳定输出风格非常有效。它通常只发送一次放在消息数组的开头。消息数组的维护你需要自己维护$messages数组。每次对话都要将用户的提问user和模型的回复assistant追加进去再发起下一次chat请求。这样模型才能看到完整的对话历史。上下文长度与截断模型有上下文窗口限制例如Llama 2是4096个token。当对话轮数增多$messages数组会变得很大。你需要实现一个逻辑在token数接近上限时丢弃最早的一些对话轮次但通常保留系统消息或者进行智能摘要。Ollama服务本身可能不会自动处理超长上下文发送过长的消息会导致错误。性能考量每次发送整个历史上下文意味着网络传输和数据处理的负载会随着对话进行而增加。对于超长对话需要考虑更高级的上下文管理方案。4.4 模型管理以编程方式操控模型库除了对话库也提供了完整的模型管理功能让你能在代码中自动化模型的准备过程。// 1. 列出所有本地模型 $localModels $ollama-list(); echo 本地可用模型:\n; foreach ($localModels-models as $model) { echo - {$model-name} (大小: {$model-size})\n; } // 2. 拉取一个不存在的模型例如 codellama:7b try { echo 正在拉取 codellama:7b 模型...\n; $pullStream $ollama-pull(model: codellama:7b, stream: true); foreach ($pullStream as $status) { // 流式输出拉取进度 echo 状态: {$status-status}; if (isset($status-completed) isset($status-total)) { echo sprintf( 进度: %.1f%%, ($status-completed / $status-total) * 100); } echo \n; } echo 模型拉取完成\n; } catch (\ArdaGnsrn\Ollama\Exceptions\OllamaClientException $e) { echo 拉取失败: . $e-getMessage(); } // 3. 删除模型谨慎操作 // $ollama-delete(model: old-model:tag);自动化部署场景在Docker镜像构建或CI/CD流程中你可以编写脚本在应用启动前检查并拉取所需的特定模型版本确保运行环境的一致性。流式拉取进度可以让用户在长时间等待中看到反馈。5. 集成到真实项目以Laravel为例让我们看一个更贴近实战的例子在Laravel中构建一个简单的AI问答命令行工具Artisan Command和一个API接口。5.1 创建Artisan命令首先创建一个命令来与模型交互。php artisan make:command AskAI编辑app/Console/Commands/AskAI.phpnamespace App\Console\Commands; use Illuminate\Console\Command; use ArdaGnsrn\Ollama\Ollama; use GuzzleHttp\Client; class AskAI extends Command { protected $signature ai:ask {prompt : 要提问的内容} {--modelllama2 : 使用的模型默认llama2} {--stream : 是否使用流式输出}; protected $description 向Ollama模型提问; public function handle() { $ollama new Ollama(client: new Client([timeout 120]), baseUrl: config(services.ollama.host)); $prompt $this-argument(prompt); $model $this-option(model); $stream $this-option(stream); $this-info(向模型 {$model} 提问: {$prompt}); if ($stream) { $this-streamResponse($ollama, $model, $prompt); } else { $this-blockResponse($ollama, $model, $prompt); } return Command::SUCCESS; } private function streamResponse(Ollama $ollama, string $model, string $prompt): void { $stream $ollama-generate(model: $model, prompt: $prompt, stream: true); $this-output-write(comment助手: /comment); foreach ($stream as $chunk) { if (!empty($chunk-response)) { $this-output-write($chunk-response); } } $this-newLine(); } private function blockResponse(Ollama $ollama, string $model, string $prompt): void { $response $ollama-generate(model: $model, prompt: $prompt); $this-line(comment助手:/comment . $response-response); $this-line(fggray生成耗时: {$response-total_duration / 1e9} 秒/); } }配置服务地址在config/services.php中添加ollama [ host env(OLLAMA_HOST, http://localhost:11434), ],然后在.env文件中设置OLLAMA_HOST。使用命令# 普通模式 php artisan ai:ask PHP中trait的作用是什么 # 流式模式 php artisan ai:ask 写一首关于代码的诗 --stream # 指定模型 php artisan ai:ask 解释一下RESTful API --modelmistral5.2 构建一个流式问答API创建一个控制器来处理Web请求并返回流式响应。// app/Http/Controllers/AIController.php namespace App\Http\Controllers; use App\Http\Controllers\Controller; use ArdaGnsrn\Ollama\Ollama; use GuzzleHttp\Client; use Illuminate\Http\Request; use Symfony\Component\HttpFoundation\StreamedResponse; class AIController extends Controller { public function chat(Request $request) { $prompt $request-input(prompt, 你好); $model $request-input(model, llama2); $ollama new Ollama(client: new Client(), baseUrl: config(services.ollama.host)); // 返回一个StreamedResponse return new StreamedResponse(function () use ($ollama, $model, $prompt) { // 设置SSE所需的头部 header(Content-Type: text/event-stream); header(Cache-Control: no-cache); header(X-Accel-Buffering: no); // 禁用Nginx缓冲 $stream $ollama-generate(model: $model, prompt: $prompt, stream: true); foreach ($stream as $chunk) { if (!empty($chunk-response)) { // 按照SSE格式发送数据 echo data: . json_encode([content $chunk-response]) . \n\n; ob_flush(); flush(); } // 可选发送进度信息 // if (isset($chunk-eval_count)) { // echo event: progress\ndata: {\eval_count\: {$chunk-eval_count}}\n\n; // ob_flush(); // flush(); // } } // 发送结束标记 echo event: done\ndata: {}\n\n; ob_flush(); flush(); }); } }前端JavaScript示例div idresponse/div input typetext idinput placeholder输入你的问题 button onclickask()发送/button script async function ask() { const prompt document.getElementById(input).value; const responseDiv document.getElementById(response); responseDiv.innerHTML em思考中.../em; const eventSource new EventSource(/api/chat?prompt${encodeURIComponent(prompt)}); eventSource.onmessage function(event) { const data JSON.parse(event.data); responseDiv.innerHTML data.content; }; eventSource.onerror function(err) { console.error(EventSource failed:, err); eventSource.close(); responseDiv.innerHTML brstrong连接出错或已完成。/strong; }; // 监听自定义的结束事件 eventSource.addEventListener(done, function() { eventSource.close(); responseDiv.innerHTML brstrong[对话结束]/strong; }); } /script关键部署提醒Nginx/Apache配置对于流式响应需要确保Web服务器不会缓冲代理响应。对于Nginx在相关location块中添加proxy_buffering off;。PHP配置确保max_execution_time足够长或者考虑使用set_time_limit(0)在脚本中取消时间限制需谨慎。连接数每个流式请求都会保持一个长期连接在高并发场景下需要考虑服务器资源。6. 性能调优、错误处理与安全考量6.1 性能优化实践将大模型集成到Web应用中性能是需要严肃对待的问题。连接池与客户端复用不要在每次请求中都新建Ollama和GuzzleHttp\Client实例。应该在服务容器中将其注册为单例如Laravel的Singleton让HTTP客户端保持连接池减少TCP连接建立的开销。超时设置为HTTP客户端设置合理的连接超时connect_timeout和读取超时read_timeout。生成文本的请求读取超时应设置得较长如60-300秒而list、show等管理请求可以较短5-10秒。异步与非阻塞对于不需要即时响应的后台任务如批量生成内容、训练数据可以考虑使用Laravel的队列Queue或Swoole等异步框架将Ollama请求放入队列异步处理避免阻塞Web请求线程。模型选择不同模型大小7B, 13B, 70B对速度和资源消耗影响巨大。在满足需求的前提下选择更小的模型通常能获得更快的响应。codellama:7b在代码相关任务上可能比llama2:13b更快且效果相当。参数调优调整生成参数能显著影响速度。减少num_predict最大生成长度能直接缩短生成时间。降低temperature和top_p可能使模型输出更确定、更快收敛。6.2 全面的错误处理与重试机制网络服务总是不稳定的完善的错误处理是生产级应用的基石。use GuzzleHttp\Exception\ConnectException; use GuzzleHttp\Exception\RequestException; function askWithRetry(Ollama $ollama, string $prompt, int $maxRetries 2) { $retryCount 0; $lastException null; while ($retryCount $maxRetries) { try { return $ollama-generate(model: llama2, prompt: $prompt); } catch (ConnectException $e) { // 网络连接错误如Ollama服务未启动 $lastException $e; $this-warn(连接Ollama服务失败重试 {$retryCount}/{$maxRetries}...); sleep(pow(2, $retryCount)); // 指数退避 $retryCount; } catch (\ArdaGnsrn\Ollama\Exceptions\OllamaClientException $e) { // Ollama API返回的错误如模型不存在、参数错误 $errorBody json_decode($e-getResponseBody(), true); if (isset($errorBody[error]) str_contains($errorBody[error], model)) { // 模型不存在可能是需要拉取 throw new \Exception(模型不存在请先使用 ollama pull llama2 拉取。); } // 其他API错误直接抛出 throw $e; } catch (\Exception $e) { // 其他未知错误 throw $e; } } throw new \Exception(请求失败已重试{$maxRetries}次。最后错误: . $lastException-getMessage()); }常见错误类型ConnectException无法连接到Ollama服务。检查服务是否运行、主机端口是否正确、防火墙设置。OllamaClientExceptionOllama服务返回了错误状态码如404模型未找到400参数错误。需要解析响应体获取具体信息。生成超时模型生成时间过长超过HTTP客户端设置的read_timeout。需要根据任务调整超时时间或优化提示词。上下文过长发送的对话历史超过了模型的上下文窗口。需要在应用层实现上下文截断或摘要功能。6.3 安全与生产环境部署建议服务隔离Ollama服务最好部署在独立的服务器或容器内与Web应用隔离。通过内部网络如Docker网络通信不要将Ollama的11434端口直接暴露到公网。访问控制如果必须暴露API考虑在Ollama服务前设置反向代理如Nginx并配置HTTP Basic认证、API密钥或IP白名单。Ollama本身目前缺乏内置的强认证机制。输入净化Prompt Sanitization永远不要将未经处理的用户输入直接作为提示词发送给模型。这可能导致提示词注入攻击诱导模型执行非预期操作或泄露系统信息。应对用户输入进行严格的过滤和转义。输出过滤与审查模型生成的内容可能包含偏见、有害信息或不准确内容。在生产环境中应对输出内容进行必要的审查和过滤特别是面向公众的应用。资源监控监控运行Ollama服务的服务器的GPU/CPU、内存和显存使用情况。大模型推理非常消耗资源需要防止单个请求耗尽资源影响其他服务。依赖版本锁定在composer.json中锁定ardagnsrn/ollama-php的版本避免因库的自动更新导致不兼容。7. 进阶应用场景与扩展思路掌握了基础用法后可以探索更复杂的集成模式。场景一构建知识库问答RAG这是当前最实用的应用之一。结合向量数据库如Chroma、Weaviate、Qdrant或PGVector你可以让模型基于你自己的文档如公司Wiki、产品手册、代码库进行回答。文档处理将你的文档切分成片段chunk。向量化使用嵌入模型Ollama也支持运行nomic-embed-text等嵌入模型将每个片段转换为向量。存储将向量和原文存储到向量数据库。检索当用户提问时将问题也向量化在向量数据库中检索出最相关的几个文档片段。增强提示将这些片段作为上下文与用户问题一起构造成一个详细的提示词发送给Ollama模型生成最终答案。ollama-php在这里负责第5步与LLM模型交互。你可以设计一个复杂的提示词模板将检索到的上下文和问题巧妙结合。场景二代码生成与审查利用codellama等代码专用模型可以构建代码补全工具集成到IDE或编辑器插件中根据当前代码上下文提供建议。代码审查助手将代码变更diff发送给模型让其从代码风格、潜在bug、安全漏洞等角度给出审查意见。代码解释器将一段复杂的代码发送给模型让其生成逐行注释或整体功能说明。场景三多模态探索未来虽然当前的ollama-php主要围绕文本API但Ollama已经开始支持多模态模型如LLaVA。未来这个库很可能会扩展出处理图像上传和分析的API。你可以提前构思应用比如构建一个能描述图片内容的服务或者一个根据草图生成前端代码的工具。扩展库本身如果你发现库缺少某个需要的Ollama API例如模型创建create、模型信息show的更详细字段可以查阅Ollama的官方API文档然后向ollama-php项目提交Pull Request或者在自己的项目中扩展这个客户端类。库的代码结构通常比较清晰遵循PSR标准扩展起来并不困难。8. 常见问题排查与调试技巧在实际使用中你肯定会遇到各种问题。这里记录一些典型问题的排查思路。问题1连接被拒绝 (Connection refused)症状cURL error 7: Failed to connect to localhost port 11434: Connection refused排查服务是否运行在终端执行ollama serve或systemctl status ollama(Linux) 检查Ollama服务状态。端口监听执行netstat -tulpn | grep 11434(Linux/macOS) 或Get-NetTCPConnection -LocalPort 11434(Windows PowerShell) 查看端口是否被监听。防火墙检查本地防火墙是否阻止了11434端口的连接。Docker网络如果Ollama运行在Docker容器内确保PHP应用能访问到该容器的网络使用容器名或IP而不是localhost。问题2模型不存在 (Model not found)症状Error: model llama2 not found排查确认模型名运行ollama list查看本地确切的模型名称和标签。可能是llama2:latest或llama2:13b。拉取模型如果本地没有使用ollama pull llama2拉取。在代码中可以先调用list()检查如果没有则调用pull()但这会是一个同步的长时间操作不适合在实时请求中做。问题3流式响应不工作一次性全部返回症状设置了streamtrue但前端还是一直等到所有内容生成完才一次性收到。排查输出缓冲这是最常见原因。确保在每次echo数据后立即调用ob_flush()和flush()。Web服务器缓冲Nginx默认会缓冲代理响应。在Nginx配置的location块中添加proxy_buffering off;和proxy_cache off;。PHP配置检查output_buffering是否被开启。可以在脚本开始时用while (ob_end_flush());关闭所有输出缓冲层。前端EventSource检查浏览器控制台是否有网络错误确认EventSource连接已正确建立。问题4响应速度极慢症状一个简单的问答需要几十秒。排查模型大小确认你运行的不是70B等超大参数模型。对于大多数任务7B或13B模型已足够。硬件资源检查服务器CPU/GPU使用率。Ollama默认会使用GPU如果可用否则使用CPU。CPU推理会慢很多。确保已正确配置GPU驱动和CUDA如果使用NVIDIA GPU。生成参数检查num_predict是否设置得过大。尝试将其降低。提示词长度过长的提示词尤其是包含大量上下文的对话会拖慢速度。考虑精简上下文。并发请求Ollama服务本身处理并发请求的能力有限。如果同时有多个请求可能会排队。考虑使用队列或限制并发。调试技巧开启详细日志在初始化Guzzle客户端时可以添加日志中间件来记录所有HTTP请求和响应的细节这对于排查通信问题非常有用。use GuzzleHttp\HandlerStack; use GuzzleHttp\Middleware; use GuzzleHttp\MessageFormatter; $stack HandlerStack::create(); $stack-push(Middleware::log( new \Monolog\Logger(OllamaClient), new MessageFormatter({req_headers} {req_body} - {res_headers} {res_body}) )); $client new Client([handler $stack]);直接测试API使用curl或Postman直接调用Ollama的API (http://localhost:11434/api/generate)排除PHP客户端的问题。查看Ollama日志启动Ollama时添加--verbose标志或在服务日志中查看更详细的运行信息。