Ollama PHP：让 PHP 应用直接调用本地大模型的轻量级桥梁

Ollama 官方 Logo

一、痛点故事：为什么需要这个库？

假设你正在用 Laravel 构建一个企业内部知识库问答系统。用户提交问题，后端需要调用大语言模型生成答案。主流的做法是调用 OpenAI API——但这意味着你的数据必须上传到第三方服务器。对于医疗、金融、政府等数据敏感行业，这几乎是不可接受的合规风险。

另一个选项是自行部署开源大模型。Ollama 正是这个场景的最佳拍档：一条命令拉起模型，本地 HTTP 接口即开即用。但 PHP 开发者面对 Ollama 的原始 JSON API，需要自己处理请求封装、响应解析、流式输出——这些胶水代码既繁琐又容易出错。

ollama-php 的出现，就是来解决这个问题的。它为 PHP 8.1+ 提供了一套完整的 Ollama API 封装，让 PHP 开发者像调用本地函数一样自然地使用本地大模型。

二、项目背景与作者

项目作者为 Arda GUNSUREN，一名独立开发者。仓库采用 MIT 许可证，截至分析时已收获约 210 颗 GitHub Stars 和 22 个 Fork，尚未合并到 Packagist 的正式发行版，但已可通过 composer require 直接从 GitHub 安装。

项目作者 Arda GUNSUREN

三、核心功能：五大 API 资源全覆盖

ollama-php 对 Ollama 提供的每一类 API 都实现了对应的 PHP 封装：

1. Completions（补全）：基础的文本续写接口。给定 prompt，模型补全后续内容。支持流式和非流式两种调用方式，API 设计简洁：

$client = \ArdaGnsrn\Ollama\Ollama::client();
$completions = $client->completions()->create([
    'model' => 'llama3.1',
    'prompt' => 'Once upon a time',
]);
echo $completions->response;

2. Chat（对话）：多轮对话接口，支持 system/user/assistant 三种角色传入多消息上下文。这是目前与大模型交互最主流的方式，ollama-php 的封装让多轮对话的上下文管理变得极为简洁。

$response = $client->chat()->create([
    'model' => 'llama3.1',
    'messages' => [
        ['role' => 'system', 'content' => 'You are a helpful assistant'],
        ['role' => 'user', 'content' => 'Hello!'],
    ],
]);
echo $response->message->content;

3. Models（模型管理）：完整封装了 Ollama 的模型管理 API，包括列表查看（list()）、详情查看（show()）、创建（create()）、删除（delete()）、复制（copy()）、拉取（pull()）和推送（push()）。借助流式封装，还可以实时展示模型下载进度。

4. Blobs（二进制大对象）：Ollama 的模型存储层 API，提供了 exists() 和 create() 两个方法，用于检查或注册模型文件 SHA256 哈希值。

5. Embed（向量嵌入）：将文本转换为高维向量表示，是 RAG（检索增强生成）系统的核心组件。通过 embed()->create() 即可获取文本的 embedding 向量。

四、Tool Calling：让 AI 调用外部函数

ollama-php 最重要的进阶功能是对 Tool Calling（函数调用） 的支持。这是目前大模型在生产环境中落地的关键技术——模型可以判断用户意图，主动调用你定义的外部函数，并将结果回传形成完整的多轮交互闭环。

例如，当用户问"今天北京天气怎么样？"时，模型可以自动识别需要调用 get_current_weather 函数，解析出 location="北京" 和 format="celsius" 参数后返回调用结果：

$response = $client->chat()->create([
    'model' => 'llama3.1',
    'messages' => [['role' => 'user', 'content' => 'What is the weather in Beijing?']],
    'tools' => [[
        'type' => 'function',
        'function' => [
            'name' => 'get_current_weather',
            'description' => 'Get the current weather',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'location' => ['type' => 'string', 'description' => 'City name'],
                    'format' => ['type' => 'string', 'enum' => ['celsius', 'fahrenheit']],
                ],
                'required' => ['location', 'format'],
            ],
        ],
    ]],
]);
// $response->message->toolCalls[0]->function->name === 'get_current_weather'
// $response->message->toolCalls[0]->function->arguments === ['location' => 'Beijing', 'format' => 'celsius']

不过需要注意的是，Tool Calling 与流式输出（createStreamed）互斥——Ollama 的流式 API 在返回 tool_calls 时存在限制，因此库设计之初就做出了这一约束，调用时若同时传入会抛出 InvalidArgumentException。

五、技术架构：经典资源分层模式

代码结构清晰，采用了典型的分层设计：

src/
  Ollama.php              # 入口类，提供链式 API（client()）
  OllamaClient.php        # HTTP 通信层，基于 Guzzle HTTP Client
  Contracts/              # 接口定义（6个接口）
  Resources/              # 业务逻辑层（Completions/Chat/Models/Blobs/Embed）
  Responses/              # 响应对象层（强类型 DTO）
    Chat/                 # Chat 相关响应（Message/ToolCall/ToolCallFunction）
    Completions/          # Completion 响应
    Embed/                # Embed 向量响应
    Models/               # Models 相关响应
    StreamResponse.php    # 流式响应封装

OllamaClient 是整个库的通信核心，基于 Guzzle 7.9+ 实现 HTTP 请求，支持自定义 base URL（默认 http://localhost:11434）和 API Key（Bearer Token 认证）。Guzzle 的异常处理机制被完整保留，网络错误会抛出 GuzzleException，便于调用方统一处理。

Resources 层每个类都对应一个 Ollama API 端点，通过 OllamaClient 发送请求，然后构造对应的 Response 对象返回。Response 对象均为不可变值对象（immutable），通过 from() 工厂方法从数组构造，提供了 toArray() 序列化方法和强类型 getter。

Contracts 层定义了每个 Resource 的接口契约，确保了类型安全和多态扩展性。如果开发者需要自定义 HTTP 中间件或 Mock 测试，只需要实现对应接口即可。

六、部署方式：Composer 依赖一键安装

作为纯 Composer 包，部署流程极为简单：

# 安装
composer require ardagnsrn/ollama-php

# 前提条件
# 1. PHP >= 8.1
# 2. 本地运行 Ollama 服务（默认端口 11434）

无 Docker 支持、无 docker-compose 文件，属于纯开发库定位。硬件需求极低（512MB RAM、50MB 磁盘），因为真正的模型推理负载完全由 Ollama 进程承担。

七、代码质量评估

维度	评分	说明
代码结构	★★★★★	PSR-4 自动加载，接口驱动，层次分明
类型安全	★★★★★	全部 PHP 8.1 强类型声明，strict_types 未开启但签名完整
测试覆盖	★★★★☆	Pest 测试框架，核心 Resource 有测试文件
文档质量	★★★★☆	README 示例丰富，但缺少架构说明文档
流式处理	★★★★★	Generator + yield 实现，低内存流式解析
Tool Calling	★★★★☆	完整支持但文档未展开说明

代码评分：85/100。库体积小但功能完整，代码可读性极高，适合作为 PHP 生态接入本地大模型的入门级首选方案。

八、局限与注意事项

1. 无 Web UI：这是一个纯开发库，没有配套的管理界面或可视化面板，不适合非技术人员使用。
2. 依赖 Ollama 本身：库的运行完全依赖用户本地安装并运行 Ollama 服务，对于不熟悉命令行的开发者有一定门槛。
3. 非官方维护：并非 Ollama 官方出品，跟进 Ollama 新 API 版本可能存在时滞。
4. 生产环境验证：Stars 数量相对较少（210），在大型生产项目的使用案例和稳定性验证方面资料不足。

九、行业意义

ollama-php 代表了一个重要趋势：AI 能力本地化。随着 Llama 3.1、Mistral、Gemma 等开源模型的能力持续提升，越来越多的开发者希望在自有基础设施上运行大模型，而非依赖闭源 API。PHP 作为 Web 开发领域使用最广的语言之一（WordPress、Laravel、Symfony 的生态基础），其开发者群体对本地 AI 能力的需求不容忽视。

ollama-php 以约 50KB 的轻量体积，完整桥接了 PHP 生态与本地大模型，预计在 PHP+Laravel 生态中会持续获得关注和社区贡献。