Teamones Embedding SDK

统一多模态向量化 SDK，支持 Doubao / OpenAI / GLM，提供 文本、图片 URL、视频 URL 的向量生成，支持 多模态向量归一化与拼接，PHP 7.4 完全兼容。

---

特性

• 多 Provider 支持：Doubao / OpenAI / GLM
• 多模态输入（Doubao）：文本、图片 URL、视频 URL
• OpenAI / GLM 自动提取文本部分
• 默认向量参数：dimensions=1024，encoding_format=float，用户可覆盖
• HTTP 请求异常捕获 & 超时处理
• 多模态向量归一化 + 拼接，直接输出统一向量
• 简单易用，统一接口

---

安装

composer require teamones/embedding

---

使用示例

1. Doubao 多模态向量

<?php
require 'vendor/autoload.php';

use Teamones\Embedding\Client;

$client = new Client('doubao', [
    'endpoint' => 'https://ark.cn-beijing.volces.com/api/v3/embeddings',
    'api_key' => '你的API_KEY',
    'timeout' => 10
]);

$input = [
    ["type"=>"text","text"=>"天很蓝"],
    ["type"=>"image_url","image_url"=>["url"=>"https://example.com/image.png"]],
    ["type"=>"video_url","video_url"=>["url"=>"https://example.com/video.mp4"]]
];

try {
    // 返回 EmbeddingResponse 对象
    $response = $client->embed(
        $input,
        "doubao-embedding-vision-251215",
        ["dimensions"=>512,"encoding_format"=>"float"]
    );

    print_r($response->vectors);

    // 返回统一多模态向量
    $unifiedVector = $client->embed(
        $input,
        "doubao-embedding-vision-251215",
        ["dimensions"=>512,"encoding_format"=>"float"],
        true // unified = true
    );

    echo "统一向量长度: " . count($unifiedVector) . PHP_EOL;
    print_r(array_slice($unifiedVector, 0, 10)); // 仅示例前10维

} catch (\RuntimeException $e) {
    echo "请求异常: " . $e->getMessage() . PHP_EOL;
}

---

2. OpenAI / GLM 向量（仅文本）

$clientOpenAI = new Client('openai', [
    'endpoint' => 'https://api.openai.com/v1/embeddings',
    'api_key' => '你的OPENAI_KEY'
]);

$inputMulti = [
    "天很蓝",
    ["type"=>"text","text"=>"太阳明亮"],
    ["type"=>"image_url","image_url"=>["url"=>"xxx"]] // 会自动忽略
];

$unifiedVector = $clientOpenAI->embed(
    $inputMulti,
    "text-embedding-3-small",
    ["dimensions"=>256],
    true
);

echo "统一文本向量长度: " . count($unifiedVector) . PHP_EOL;

---

参数说明

参数	说明	默认值
dimensions	向量维度	1024
encoding_format	向量编码格式	float
timeout	HTTP 请求超时（秒）	10
unified	是否返回归一化拼接后的向量	false

---

异常处理

• HTTP 请求异常、非 200 返回码 → 抛出 \RuntimeException
• JSON 解析失败 → 抛出 \RuntimeException
• 超时或网络异常 → 抛出 \RuntimeException

示例：

try {
    $vector = $client->embed($input, $model, [], true);
} catch (\RuntimeException $e) {
    echo "请求异常: " . $e->getMessage();
}

---

安全与注意事项

• Doubao 多模态只支持 URL 方式，不支持 base64 输入
• OpenAI / GLM 仅支持文本输入，多模态输入会自动忽略非文本
• 用户可以通过 $opt 覆盖默认参数 dimensions / encoding_format

---

依赖

• PHP >= 7.4
• yurunsoft/yurun-http

---