大模型应用开发 / 系统课时
接入嵌入模型
接入嵌入模型
本节完成 RAG 检索前最关键的向量化步骤:把一批文本发送到兼容 Embeddings 的 HTTP 接口,取得向量后校验数量、维度和数值有效性,并在客户端提前拦截过大的批次与过长输入。
学习目标
- 调用嵌入接口把文本转换为浮点向量
- 验证返回向量的条数、维度和数值有效性
- 为批量大小与输入长度建立可配置的客户端保护
配置嵌入访问参数
嵌入模型与生成模型可以使用不同地址、密钥和限额,因此单独配置更容易维护。EMBED_MAX_BATCH_SIZE 与 EMBED_MAX_INPUT_CHARS 是客户端保护值,不代表供应商的硬限制,应按所用服务文档调整。
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 进程读取;配置动作本身不会产生固定控制台输出。随后先确认模型名和本地批量上限已加载。
python -c "import os; print(os.environ['EMBED_MODEL']); print(os.environ['EMBED_MAX_BATCH_SIZE'])"预期输出
<MODEL>
32批量生成并校验向量
下面示例使用 Python 标准库调用兼容 /embeddings 的接口。校验放在返回业务层之前:少一条向量、维度不一致或出现非有限数值时立即失败,避免把坏数据写入向量库。
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)}")预期输出
count=2
dimension=<VALUE>
finite=True<VALUE> 取决于实际嵌入模型。真正写入向量库时,应把这个维度与向量字段或索引配置保持一致;更换嵌入模型前也要重新核对维度,不能假设不同模型兼容。
理解批量与输入长度限制
批量请求能减少网络往返,但单次输入越多,越容易触发请求体大小、令牌数或服务端批量上限。客户端先限制条数,可以把明显不合法的请求挡在本地;生产系统通常再按批次循环发送,而不是一次提交所有文档。
EMBED_MAX_INPUT_CHARS 只是简单的字符级保护。很多服务真正按 token 计费和限制,同样长度的中文、英文、代码可能消耗不同 token 数。需要精确控制时,应使用与目标模型匹配的 tokenizer 计算 token,再按供应商上限切分文本。
写入向量库前的验收
至少检查三件事:输入条数与返回条数一致、所有向量维度一致、每个元素都是有限数值。随后用同一个嵌入模型分别编码文档与查询,才能让向量距离具有可比较意义。
如果接口返回 400 或 413,应先检查批量与输入长度;401/403 检查鉴权;429 说明需要降速或退避;5xx 与网络超时才更适合有限次数重试。完成这些保护后,嵌入层就能稳定地为后续向量存储和相似度检索提供输入。