Source: Dev.to

Laravel와 OpenAI API 통합 방법 (완전 가이드 2026)

Laravel는 가장 인기 있는 PHP 프레임워크이며, 공식 openai-php/client 라이브러리를 사용하면 OpenAI를 손쉽게 추가할 수 있습니다. 이 가이드에서는 설치, 서비스 클래스, 채팅 컨트롤러, 스트리밍, 오류 처리, 테스트까지 모두 다룹니다.

요구 사항

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

Step 1: Install

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

Step 2: .env

OPENAI_API_KEY=sk-proj-...

Step 3: OpenAIService

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

class OpenAIService
{
    public function chat(array $messages, string $model = 'gpt-4o-mini'): string
    {
        $response = OpenAI::chat()->create(['model' => $model, 'messages' => $messages]);
        return $response->choices[0]->message->content;
    }
}

Step 4: ChatController

public function send(Request $request): JsonResponse
{
    $messages = $request->input('history', []);
    $messages[] = ['role' => 'user', 'content' => $request->input('message')];
    $reply = $this->openAI->chat($messages);
    return response()->json(['reply' => $reply, 'messages' => [...$messages,
        ['role' => 'assistant', 'content' => $reply]]]);
}

Step 5: Streaming SSE

return response()->stream(function () use ($messages) {
    foreach ($this->openAI->stream($messages) as $chunk) {
        echo "data: " . json_encode(['chunk' => $chunk]) . "\n\n";
        ob_flush(); flush();
    }
    echo "data: [DONE]\n\n";
}, 200, ['Content-Type' => 'text/event-stream', 'Cache-Control' => 'no-cache']);

Error Handling

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

try {
    $reply = $this->openAI->chat($messages);
} catch (ErrorException $e) {
    return response()->json(['error' => 'AI 서비스 오류가 발생했습니다.'], 503);
} catch (TransporterException $e) {
    return response()->json(['error' => '연결에 실패했습니다.'], 503);
}

Testing

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

Summary

composer require openai-php/laravel + .env 파일에 OPENAI_API_KEY 추가

• 서비스 클래스로 컨트롤러를 깔끔하게 유지하고, response()->stream() 과 SSE 로 스트리밍 구현
• 실제 API를 호출하지 않고 단위 테스트를 할 수 있도록 OpenAI::fake() 사용

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