> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本向量化（Embedding）

> 将文本转换为向量嵌入，适用于语义搜索、文本相似度计算、聚类分析等场景

## 简介

将文本转换为向量嵌入，适用于语义搜索、文本相似度计算、聚类分析等场景。

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 请求参数

<ParamField body="model" type="string" required>
  模型名称，如 `text-embedding-3-small`、`text-embedding-3-large`
</ParamField>

<ParamField body="input" type="string | array" required>
  要嵌入的文本，可以是字符串或字符串数组
</ParamField>

<ParamField body="encoding_format" type="string">
  返回格式：`float` 或 `base64`
</ParamField>

<ParamField body="dimensions" type="integer">
  输出向量维度（仅部分模型支持）
</ParamField>

## cURL 示例

```bash theme={null}
curl https://api.mixroute.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "你好，世界"
  }'
```

## Python 示例

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.mixroute.ai/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="你好，世界"
)

print(response.data[0].embedding)
print(f"向量维度：{len(response.data[0].embedding)}")
```

## 支持的模型

| 模型                     | 维度   | 说明              |
| ---------------------- | ---- | --------------- |
| text-embedding-3-small | 1536 | 高性价比，适合大多数场景    |
| text-embedding-3-large | 3072 | 高精度，适合对精度要求高的场景 |
| text-embedding-ada-002 | 1536 | 旧版模型            |

## 注意事项

* 部分模型支持通过 `dimensions` 参数自定义输出维度
* 批量嵌入时，`input` 可传入字符串数组

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mixroute.ai/v1/embeddings \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "text-embedding-3-small",
      "input": "你好，世界"
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-xxxxxxxxxx",
      base_url="https://api.mixroute.ai/v1"
  )

  response = client.embeddings.create(
      model="text-embedding-3-small",
      input="你好，世界"
  )
  print(response.data[0].embedding)
  ```

  ```javascript JavaScript theme={null}
  const OpenAI = require('openai');

  const client = new OpenAI({
    apiKey: 'sk-xxxxxxxxxx',
    baseURL: 'https://api.mixroute.ai/v1'
  });

  const response = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: '你好，世界'
  });
  console.log(response.data[0].embedding);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1/embeddings', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
      ],
      'json' => [
          'model' => 'text-embedding-3-small',
          'input' => '你好，世界'
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "context"
      "fmt"
      openai "github.com/sashabaranov/go-openai"
  )

  func main() {
      config := openai.DefaultConfig("sk-xxxxxxxxxx")
      config.BaseURL = "https://api.mixroute.ai/v1"
      client := openai.NewClientWithConfig(config)

      resp, _ := client.CreateEmbeddings(
          context.Background(),
          openai.EmbeddingRequest{
              Model: "text-embedding-3-small",
              Input: []string{"你好，世界"},
          },
      )
      fmt.Println(resp.Data[0].Embedding)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
          "model": "text-embedding-3-small",
          "input": "你好，世界"
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/embeddings"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/embeddings')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request.body = {
    model: 'text-embedding-3-small',
    input: '你好，世界'
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.0023064255, -0.009327292, 0.015797347, ...]
      }
    ],
    "model": "text-embedding-3-small",
    "usage": {
      "prompt_tokens": 5,
      "total_tokens": 5
    }
  }
  ```
</ResponseExample>