docs/zh/api-reference/embedding-api.md

Embedding API 参考文档

概述

AxonHub 通过 OpenAI 兼容和 Jina AI 专用 API 提供全面的文本和多模态嵌入生成支持。

主要优势

• OpenAI 兼容性：无需修改即可使用现有的 OpenAI SDK
• Jina AI 支持：原生支持 Jina 嵌入格式，适用于特殊用例
• 多种输入类型：支持单文本、文本数组、Token 数组和多个 Token 数组
• 灵活的输出格式：可选择浮点数组或 base64 编码的嵌入向量

支持的端点

端点：

• POST /v1/embeddings - OpenAI 兼容的嵌入 API
• POST /jina/v1/embeddings - Jina AI 专用的嵌入 API

请求格式

{
  "input": "要嵌入的文本",
  "model": "text-embedding-3-small",
  "encoding_format": "float",
  "dimensions": 1536,
  "user": "用户ID"
}

参数：

参数	类型	必填	描述
input	string | string[] | number[] | number[][]	✅	要嵌入的文本。可以是单个字符串、字符串数组、Token 数组或多个 Token 数组。
model	string	✅	用于生成嵌入的模型。
encoding_format	string	❌	返回嵌入的格式。可选 float 或 base64。默认：float。
dimensions	integer	❌	输出嵌入的维度数。
user	string	❌	终端用户的唯一标识符。

Jina 专用参数：

参数	类型	必填	描述
task	string	❌	Jina 嵌入的任务类型。选项：text-matching、retrieval.query、retrieval.passage、separation、classification、none。

响应格式

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.123, 0.456, ...],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4
  }
}

示例

OpenAI SDK (Python)

import openai

client = openai.OpenAI(
    api_key="your-axonhub-api-key",
    base_url="http://localhost:8090/v1"
)

response = client.embeddings.create(
    input="Hello, world!",
    model="text-embedding-3-small"
)

print(response.data[0].embedding[:5])  # 前 5 个维度

OpenAI SDK (Go)

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
)

func main() {
    client := openai.NewClient(
        option.WithAPIKey("your-axonhub-api-key"),
        option.WithBaseURL("http://localhost:8090/v1"),
    )

    embedding, err := client.Embeddings.New(context.TODO(), openai.EmbeddingNewParams{
        Input: openai.Union[string](openai.String("Hello, world!")),
        Model: openai.String("text-embedding-3-small"),
        option.WithHeader("AH-Trace-Id", "trace-example-123"),
        option.WithHeader("AH-Thread-Id", "thread-example-abc"),
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("嵌入维度: %d\n", len(embedding.Data[0].Embedding))
    fmt.Printf("前 5 个值: %v\n", embedding.Data[0].Embedding[:5])
}

多个文本

response = client.embeddings.create(
    input=["Hello, world!", "How are you?"],
    model="text-embedding-3-small"
)

for i, data in enumerate(response.data):
    print(f"文本 {i}: {data.embedding[:3]}...")

Jina 专用任务

import requests

response = requests.post(
    "http://localhost:8090/jina/v1/embeddings",
    headers={
        "Authorization": "Bearer your-axonhub-api-key",
        "Content-Type": "application/json"
    },
    json={
        "input": "What is machine learning?",
        "model": "jina-embeddings-v2-base-en",
        "task": "retrieval.query"
    }
)

result = response.json()
print(result["data"][0]["embedding"][:5])

认证

Embedding API 使用 Bearer Token 认证：

• 请求头: Authorization: Bearer <your-api-key>

API 密钥通过 AxonHub 的 API 密钥管理系统进行管理。

最佳实践

1. 使用追踪请求头：包含 AH-Trace-Id 和 AH-Thread-Id 请求头以获得更好的可观测性
2. 批量请求：嵌入多个文本时，在单个请求中发送以提高性能
3. 选择合适的维度：如果不需要完整的维度，使用 dimensions 参数减少嵌入大小
4. 选择合适的编码：如果需要在网络上传输嵌入，使用 base64 编码以减少负载大小
5. Jina 任务类型：使用 Jina 嵌入时，根据用例选择合适的 task 类型以优化检索质量

相关资源

• OpenAI API
• Rerank API