Laravel에 OpenAI API를 통합하는 방법 (2026년 완전 가이드)

Laravel은 가장 인기 있는 PHP 프레임워크이며, 공식 openai-php/client 라이브러리를 사용하면 OpenAI를 추가하는 과정이 매우 간단합니다. 이 가이드는 설치, 서비스 클래스 (Service Class), 채팅 컨트롤러 (Chat Controller), 스트리밍 (Streaming), 에러 핸들링 (Error Handling) 및 테스트 (Testing)를 다룹니다.

요구 사항

• Laravel 10 또는 11, PHP 8.1 이상, Composer, OpenAI API 키

1단계: 설치

composer require openai-php/laravel
php artisan vendor:publish --provider="OpenAI\Laravel\ServiceProvider"

2단계: .env

OPENAI_API_KEY=sk-proj-...

3단계: OpenAIService

namespace App\Services;
use OpenAI\Laravel\Facades\OpenAI;

...

4단계: ChatController

public function send(Request $request): JsonResponse
{
    $messages = $request->input('history', []);
...

5단계: 스트리밍 SSE (Streaming SSE)

return response()->stream(function () use ($messages) {
    foreach ($this->openAI->stream($messages) as $chunk) {
        echo "data: " . json_encode(['chunk' => $chunk]) . "\n\n";
...

에러 핸들링 (Error Handling)

use OpenAI\Exceptions\ErrorException;
use OpenAI\Exceptions\TransporterException;

...

테스트 (Testing)

OpenAI::fake([CreateResponse::fake(['choices' => [['message' => ['content' => 'Hi!']]]])]);
$reply = app(OpenAIService::class)->chat([['role' => 'user', 'content' => 'Hello']]);
$this->assertEquals('Hi!', $reply);

요약

• composer require openai-php/laravel + .env 파일에 OPENAI_API_KEY 설정
• 서비스 클래스 (Service Class)를 사용하여 컨트롤러를 깔끔하게 유지; response()->stream() + SSE를 통한 스트리밍
• 실제 API를 호출하지 않고 단위 테스트 (Unit Test)를 수행하기 위한 OpenAI::fake() 사용

원문은 kalyna.pro에서 처음 게시되었습니다.