大模型应用开发 / 系统课时

接入嵌入模型

接入嵌入模型

本节完成 RAG 检索前最关键的向量化步骤:把一批文本发送到兼容 Embeddings 的 HTTP 接口,取得向量后校验数量、维度和数值有效性,并在客户端提前拦截过大的批次与过长输入。

学习目标

  • 调用嵌入接口把文本转换为浮点向量
  • 验证返回向量的条数、维度和数值有效性
  • 为批量大小与输入长度建立可配置的客户端保护

配置嵌入访问参数

嵌入模型与生成模型可以使用不同地址、密钥和限额,因此单独配置更容易维护。EMBED_MAX_BATCH_SIZE 与 EMBED_MAX_INPUT_CHARS 是客户端保护值,不代表供应商的硬限制,应按所用服务文档调整。

bash
export EMBED_BASE_URL="<BASE_URL>"
export EMBED_API_KEY="<API_KEY>"
export EMBED_MODEL="<MODEL>"
export EMBED_TIMEOUT_SECONDS="15"
export EMBED_MAX_BATCH_SIZE="32"
export EMBED_MAX_INPUT_CHARS="8000"

预期结果

当前 Shell 会话中六个变量可被后续 Python 进程读取;配置动作本身不会产生固定控制台输出。随后先确认模型名和本地批量上限已加载。

bash
python -c "import os; print(os.environ['EMBED_MODEL']); print(os.environ['EMBED_MAX_BATCH_SIZE'])"

预期输出

text
<MODEL>
32

批量生成并校验向量

下面示例使用 Python 标准库调用兼容 /embeddings 的接口。校验放在返回业务层之前:少一条向量、维度不一致或出现非有限数值时立即失败,避免把坏数据写入向量库。

python
import json
import math
import os
import socket
from urllib import error, request

BASE_URL = os.environ["EMBED_BASE_URL"].rstrip("/")
API_KEY = os.environ["EMBED_API_KEY"]
MODEL = os.environ["EMBED_MODEL"]
TIMEOUT_SECONDS = float(os.getenv("EMBED_TIMEOUT_SECONDS", "15"))
MAX_BATCH_SIZE = int(os.getenv("EMBED_MAX_BATCH_SIZE", "32"))
MAX_INPUT_CHARS = int(os.getenv("EMBED_MAX_INPUT_CHARS", "8000"))

def validate_inputs(texts: list[str]) -> None:
    if not 1 <= len(texts) <= MAX_BATCH_SIZE:
        raise ValueError(f"batch size must be 1..{MAX_BATCH_SIZE}")
    for index, text in enumerate(texts):
        if not isinstance(text, str) or not text.strip():
            raise ValueError(f"input {index} is empty")
        if len(text) > MAX_INPUT_CHARS:
            raise ValueError(f"input {index} exceeds local char limit")

def embed(texts: list[str]) -> list[list[float]]:
    validate_inputs(texts)
    payload = json.dumps({"model": MODEL, "input": texts}).encode("utf-8")
    req = request.Request(
        f"{BASE_URL}/embeddings",
        data=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        method="POST"
    )

    try:
        with request.urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
            body = json.load(resp)
    except error.HTTPError as exc:
        detail = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(f"HTTP {exc.code}: {detail[:200]}") from exc
    except (error.URLError, TimeoutError, socket.timeout) as exc:
        raise RuntimeError(f"network error: {exc}") from exc

    try:
        items = sorted(body["data"], key=lambda item: item["index"])
        vectors = [item["embedding"] for item in items]
    except (KeyError, TypeError) as exc:
        raise RuntimeError("unexpected response schema") from exc

    if len(vectors) != len(texts):
        raise RuntimeError("embedding count mismatch")

    dimensions = {len(vector) for vector in vectors}
    if len(dimensions) != 1 or 0 in dimensions:
        raise RuntimeError("embedding dimension mismatch")

    if not all(math.isfinite(value) for vector in vectors for value in vector):
        raise RuntimeError("embedding contains non-finite value")
    return vectors

if __name__ == "__main__":
    vectors = embed(["RAG combines retrieval and generation.", "Embeddings encode semantic meaning."])
    print(f"count={len(vectors)}")
    print(f"dimension={len(vectors[0])}")
    print(f"finite={all(math.isfinite(v) for row in vectors for v in row)}")

预期输出

text
count=2
dimension=<VALUE>
finite=True

<VALUE> 取决于实际嵌入模型。真正写入向量库时,应把这个维度与向量字段或索引配置保持一致;更换嵌入模型前也要重新核对维度,不能假设不同模型兼容。

理解批量与输入长度限制

批量请求能减少网络往返,但单次输入越多,越容易触发请求体大小、令牌数或服务端批量上限。客户端先限制条数,可以把明显不合法的请求挡在本地;生产系统通常再按批次循环发送,而不是一次提交所有文档。

EMBED_MAX_INPUT_CHARS 只是简单的字符级保护。很多服务真正按 token 计费和限制,同样长度的中文、英文、代码可能消耗不同 token 数。需要精确控制时,应使用与目标模型匹配的 tokenizer 计算 token,再按供应商上限切分文本。

写入向量库前的验收

至少检查三件事:输入条数与返回条数一致、所有向量维度一致、每个元素都是有限数值。随后用同一个嵌入模型分别编码文档与查询,才能让向量距离具有可比较意义。

如果接口返回 400 或 413,应先检查批量与输入长度;401/403 检查鉴权;429 说明需要降速或退避;5xx 与网络超时才更适合有限次数重试。完成这些保护后,嵌入层就能稳定地为后续向量存储和相似度检索提供输入。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接入嵌入模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通