7. ¿Qué son los Embeddings? Vectores, Dimensiones y Distancia del Coseno

<?php
declare(strict_types=1);

// generate-embeddings.php

/**
 * Obtiene el vector numérico (1536 dimensiones) de un texto usando OpenAI.
 * @return array<int, float>
 */
function getEmbedding(string $text, string $apiKey): array
{
    $ch = curl_init('https://api.openai.com/v1/embeddings');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $apiKey
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'model' => 'text-embedding-3-small',
            'input' => $text
        ]),
        CURLOPT_TIMEOUT        => 15
    ]);

    $res = json_decode((string)curl_exec($ch), true);
    curl_close($ch);

    return $res['data'][0]['embedding'] ?? [];
}

/**
 * Calcula la Similitud del Coseno entre dos vectores matemáticos.
 * cos(theta) = (A · B) / (||A|| * ||B||)
 */
function cosineSimilarity(array $vecA, array $vecB): float
{
    $dotProduct = 0.0;
    $normA = 0.0;
    $normB = 0.0;

    $dim = count($vecA);
    for ($i = 0; $i < $dim; $i++) {
        $dotProduct += $vecA[$i] * $vecB[$i];
        $normA      += $vecA[$i] * $vecA[$i];
        $normB      += $vecB[$i] * $vecB[$i];
    }

    if ($normA === 0.0 || $normB === 0.0) {
        return 0.0;
    }

    return $dotProduct / (sqrt($normA) * sqrt($normB));
}

// Ejemplo de uso real:
$apiKey = getenv('OPENAI_API_KEY') ?: 'sk-test';

$frase1 = "¿Cómo restablezco mi contraseña de usuario olvidada?";
$frase2 = "Guía paso a paso para recuperar el acceso a tu cuenta";

$vec1 = getEmbedding($frase1, $apiKey);
$vec2 = getEmbedding($frase2, $apiKey);

if (!empty($vec1) && !empty($vec2)) {
    $score = cosineSimilarity($vec1, $vec2);
    echo "Similitud Coseno calculada: " . round($score, 4) . "\n";
    // Resultado típico: > 0.82 (altísima coincidencia semántica)
}