文本向量化（Embedding）

功能概述

文本嵌入（Text Embedding）API 可以将文本转换为高维向量表示，捕捉文本的语义信息。这些向量可用于：

语义搜索：基于含义而非关键词匹配进行搜索
文本分类：将文本自动归类到预定义类别
相似度计算：计算两段文本的语义相似程度
聚类分析：将相似文本自动分组
推荐系统：基于内容相似度进行推荐
RAG 应用：检索增强生成的核心能力

老张API 当前已验证 text-embedding-3-small、text-embedding-3-large 和 text-embedding-ada-002，接口返回结构兼容 OpenAI SDK。

快速开始

基础示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的老张API密钥",
    base_url="https://api2.laozhang.ai/v1"
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="人工智能正在改变世界"
)

# 获取向量
embedding = response.data[0].embedding
print(f"向量维度: {len(embedding)}")
print(f"前5个值: {embedding[:5]}")

cURL 示例

curl -sS "https://api2.laozhang.ai/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "人工智能正在改变世界"
  }'

响应包含 object、data、model 和 usage。data[0].embedding 是浮点数组，usage.total_tokens 是本次输入消耗的 token 数。

批量处理

一次请求处理多个文本：

texts = [
    "机器学习是人工智能的一个分支",
    "深度学习使用神经网络进行学习",
    "自然语言处理让机器理解人类语言"
]

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

# 获取所有向量
embeddings = [item.embedding for item in response.data]
print(f"处理了 {len(embeddings)} 个文本")

支持的模型

模型	默认维度	已验证降维	特点	推荐场景
`text-embedding-3-small`	1536	256 / 512	成本较低，速度快	通用场景、RAG 默认选择
`text-embedding-3-large`	3072	1024	效果最好，维度高	高精度检索和重排序前召回
`text-embedding-ada-002`	1536	不支持 `dimensions`	经典模型，兼容性好	已有系统迁移

💡 选择建议：

大多数场景使用 text-embedding-3-small 即可
对精度要求极高时使用 text-embedding-3-large

核心参数

model（必填）

指定 Embedding 模型：

model="text-embedding-3-small"   # 推荐，成本较低
model="text-embedding-3-large"   # 高精度
model="text-embedding-ada-002"   # 经典模型

input（必填）

要转换的文本，支持单个字符串或字符串数组：

# 单个文本
input="这是一段测试文本"

# 多个文本（批量处理）
input=["文本1", "文本2", "文本3"]

dimensions（可选）

指定输出向量维度（仅 v3 模型支持）：

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="测试文本",
    dimensions=512  # 降低维度，减少存储
)

dimensions 仅适用于 v3 模型。实测 text-embedding-3-small 可返回 1536 / 512 / 256 维，text-embedding-3-large 默认 3072 维，也可按需降维。降低维度可以减少存储空间和向量检索成本，但可能影响召回效果。

已验证返回结构

批量输入会按 data[].index 顺序返回，每条 embedding 的长度等于模型默认维度或传入的 dimensions：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.036377, 0.000628]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 26,
    "total_tokens": 26
  }
}

encoding_format（可选）

默认返回浮点数组。需要显式指定时可传：

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="测试文本",
    encoding_format="float"
)

实用示例

1. 计算文本相似度

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的老张API密钥",
    base_url="https://api2.laozhang.ai/v1"
)

def get_embedding(text):
    """获取文本的向量表示"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    )
    return response.data[0].embedding

def cosine_similarity(a, b):
    """计算余弦相似度"""
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# 计算两段文本的相似度
text1 = "今天天气很好"
text2 = "今天阳光明媚"
text3 = "我喜欢吃苹果"

emb1 = get_embedding(text1)
emb2 = get_embedding(text2)
emb3 = get_embedding(text3)

print(f"文本1和文本2的相似度: {cosine_similarity(emb1, emb2):.4f}")
print(f"文本1和文本3的相似度: {cosine_similarity(emb1, emb3):.4f}")

2. 语义搜索

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的老张API密钥",
    base_url="https://api2.laozhang.ai/v1"
)

# 文档库
documents = [
    "Python 是一种解释型编程语言",
    "JavaScript 常用于网页开发",
    "机器学习是人工智能的一个分支",
    "数据库用于存储和管理数据",
    "深度学习使用多层神经网络"
]

def get_embeddings(texts):
    """批量获取向量"""
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [item.embedding for item in response.data]

def semantic_search(query, docs, doc_embeddings, top_k=3):
    """语义搜索"""
    query_embedding = get_embeddings([query])[0]
    
    # 计算相似度
    similarities = []
    for i, doc_emb in enumerate(doc_embeddings):
        sim = np.dot(query_embedding, doc_emb) / (
            np.linalg.norm(query_embedding) * np.linalg.norm(doc_emb)
        )
        similarities.append((i, sim))
    
    # 排序返回最相似的文档
    similarities.sort(key=lambda x: x[1], reverse=True)
    return [(docs[i], sim) for i, sim in similarities[:top_k]]

# 预计算文档向量
doc_embeddings = get_embeddings(documents)

# 搜索
query = "什么是AI？"
results = semantic_search(query, documents, doc_embeddings)

print(f"查询: {query}")
print("搜索结果:")
for doc, score in results:
    print(f"  [{score:.4f}] {doc}")

3. 文本分类

import numpy as np
from openai import OpenAI

client = OpenAI(
    api_key="sk-你的老张API密钥",
    base_url="https://api2.laozhang.ai/v1"
)

# 类别示例
categories = {
    "技术": ["编程语言", "软件开发", "人工智能"],
    "体育": ["足球比赛", "篮球运动", "奥运会"],
    "美食": ["中餐烹饪", "西餐料理", "甜点制作"]
}

def classify_text(text, categories):
    """基于向量相似度进行分类"""
    text_emb = get_embedding(text)
    
    best_category = None
    best_score = -1
    
    for category, examples in categories.items():
        # 获取类别示例的平均向量
        example_embs = get_embeddings(examples)
        avg_emb = np.mean(example_embs, axis=0)
        
        # 计算相似度
        score = np.dot(text_emb, avg_emb) / (
            np.linalg.norm(text_emb) * np.linalg.norm(avg_emb)
        )
        
        if score > best_score:
            best_score = score
            best_category = category
    
    return best_category, best_score

# 测试分类
test_texts = [
    "Python编程入门教程",
    "世界杯足球赛精彩回顾",
    "如何做一道美味的红烧肉"
]

for text in test_texts:
    category, score = classify_text(text, categories)
    print(f"'{text}' -> {category} (置信度: {score:.4f})")

与向量数据库集成

Pinecone 集成

import pinecone
from openai import OpenAI

# 初始化
client = OpenAI(api_key="sk-xxx", base_url="https://api2.laozhang.ai/v1")
pinecone.init(api_key="pinecone-api-key")
index = pinecone.Index("my-index")

# 存储向量
def store_document(doc_id, text):
    embedding = client.embeddings.create(
        model="text-embedding-3-small",
        input=text
    ).data[0].embedding
    
    index.upsert([(doc_id, embedding, {"text": text})])

# 搜索
def search(query, top_k=5):
    query_embedding = client.embeddings.create(
        model="text-embedding-3-small",
        input=query
    ).data[0].embedding
    
    results = index.query(query_embedding, top_k=top_k, include_metadata=True)
    return results

Chroma 集成

import chromadb
from openai import OpenAI

client = OpenAI(api_key="sk-xxx", base_url="https://api2.laozhang.ai/v1")
chroma_client = chromadb.Client()
collection = chroma_client.create_collection("my_collection")

# 自定义 Embedding 函数
def get_embedding(texts):
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts
    )
    return [item.embedding for item in response.data]

# 添加文档
documents = ["文档1", "文档2", "文档3"]
embeddings = get_embedding(documents)
collection.add(
    embeddings=embeddings,
    documents=documents,
    ids=["id1", "id2", "id3"]
)

# 搜索
query_embedding = get_embedding(["搜索查询"])[0]
results = collection.query(query_embeddings=[query_embedding], n_results=3)

最佳实践

1. 批量处理

# ❌ 不好：逐个请求
for text in texts:
    embedding = get_embedding(text)

# ✅ 好：批量请求
embeddings = get_embeddings(texts)  # 一次请求处理所有文本

2. 文本预处理

def preprocess_text(text):
    """预处理文本"""
    # 去除多余空白
    text = " ".join(text.split())
    # 截断过长文本
    if len(text) > 8000:
        text = text[:8000]
    return text

3. 缓存向量

import hashlib
import json

embedding_cache = {}

def get_embedding_cached(text):
    """带缓存的向量获取"""
    cache_key = hashlib.md5(text.encode()).hexdigest()
    
    if cache_key in embedding_cache:
        return embedding_cache[cache_key]
    
    embedding = get_embedding(text)
    embedding_cache[cache_key] = embedding
    return embedding

定价说明

Embedding 按输入 token 计费，返回的 usage.total_tokens 可用于成本核算。模型价格可能调整，请以控制台价格列表和定价页面为准。

常见问题

向量维度多少合适？

通用场景：1536 维（默认）足够
存储受限：可降到 512 或 256 维
高精度需求：使用 3072 维的 large 模型

单次最多处理多少文本？

建议单次请求不超过 2000 个文本，过多可能超时。

文本长度限制是多少？

最大 8192 tokens，超过会被截断。

文本生成

使用 Chat API 进行对话

LangChain 集成

在 LangChain 中使用 Embedding

模型信息

查看所有支持的模型

Dify 配置

在 Dify 中配置向量模型

产品基础

核心 API

文本 API

视频生成 API

图像生成 API

AI 理解能力

文本向量化（Embedding）

功能概述

快速开始

基础示例

cURL 示例

批量处理

支持的模型

核心参数

model（必填）

input（必填）

dimensions（可选）

已验证返回结构

encoding_format（可选）

实用示例

1. 计算文本相似度

2. 语义搜索

3. 文本分类

与向量数据库集成

Pinecone 集成

Chroma 集成

最佳实践

1. 批量处理

2. 文本预处理

3. 缓存向量

定价说明

常见问题

相关文档

文本生成

LangChain 集成

模型信息

Dify 配置

​功能概述

​快速开始

​基础示例

​cURL 示例

​批量处理

​支持的模型

​核心参数

​model（必填）

​input（必填）

​dimensions（可选）

​已验证返回结构

​encoding_format（可选）

​实用示例

​1. 计算文本相似度

​2. 语义搜索

​3. 文本分类

​与向量数据库集成

​Pinecone 集成

​Chroma 集成

​最佳实践

​1. 批量处理

​2. 文本预处理

​3. 缓存向量

​定价说明

​常见问题

​相关文档

文本生成

LangChain 集成

模型信息

Dify 配置

功能概述

快速开始

基础示例

cURL 示例

批量处理

支持的模型

核心参数

model（必填）

input（必填）

dimensions（可选）

已验证返回结构

encoding_format（可选）

实用示例

1. 计算文本相似度

2. 语义搜索

3. 文本分类

与向量数据库集成

Pinecone 集成

Chroma 集成

最佳实践

1. 批量处理

2. 文本预处理

3. 缓存向量

定价说明

常见问题

相关文档