2.8 Embeddings API与Moderation API实战应用详解
一、Embeddings API
1.1 作用
将文本转换为高维向量，用于相似度计算、语义检索、RAG等场景。是构建向量索引与知识库的基础。《大模型应用开发极简入门》第2章「其他OpenAI API和功能」将 Embeddings API（文本向量化、相似度计算、RAG 基础）与 Moderation API（内容安全审核、违规检测）并列；本节与之一一对应，并给出调用示例与集成要点。
1.2 调用示例
from openai import OpenAI
client = OpenAI()
response = client.embeddings.create(
model="text-embedding-ada-002",
input="人工智能是计算机科学的一个分支"
)
vector = response.data[0].embedding # 1536维向量
1.3 典型应用
- RAG文档向量化
- 语义相似度计算
- 聚类与分类
二、Moderation API
2.1 作用
对用户输入或模型输出进行内容安全审核，检测违规、暴力、仇恨等有害内容。
2.2 调用示例
response = client.moderations.create(input="用户输入的文本")
result = response.results[0]
flagged = result.flagged # 是否违规
categories = result.categories # 违规类别
三、Embeddings进阶
3.1 向量维度与模型
text-embedding-ada-002输出1536维向量。不同模型维度可能不同，检索时需使用同一模型，否则向量不可比。
3.2 相似度计算
常用余弦相似度：cosine_sim(a, b) = dot(a,b) / (norm(a)*norm(b))。OpenAI的向量已归一化，余弦相似度等价于点积。
3.3 批量嵌入
单次可传入多个文本（数组），减少请求次数。注意单次有Token上限，超长需分批。
response = client.embeddings.create(
model="text-embedding-ada-002",
input=["文本1", "文本2", "文本3"]
)
vectors = [d.embedding for d in response.data]
四、Moderation进阶
4.1 类别说明
Moderation返回多个类别（如hate、hate/threatening、self-harm等）的布尔值，表示是否违规。可根据业务选择关注的类别。
4.2 输入输出
可对用户输入或模型输出分别调用，建议两端都做审核。对模型输出审核可防止生成违规内容。
4.3 与提示结合
在system中明确"不要生成违规内容"，再结合Moderation做二次校验，可形成双重保障。
五、与《大模型应用开发极简入门》第2.8节的对应
本书第2章「其他OpenAI API和功能」涵盖 Embeddings API（文本向量化、相似度计算、RAG 基础）、Moderation API（内容安全审核、违规检测），以及 Function Calling（下一节）。本节与 Embeddings、Moderation 对应：Embeddings 的调用示例与典型应用对应「文本向量化、相似度、RAG 基础」；Moderation 的调用与类别对应「内容安全审核、违规检测」。书中将 Embeddings 作为 RAG 的基础，第5章 RAG 实战会直接用到本节能力。
六、Embeddings 在 RAG 中的角色
RAG（检索增强生成）的典型流程：将文档分块 → 用 Embeddings API 将每块转为向量 → 存入向量库；用户提问时，将问题转为向量 → 在向量库中检索最相似的块 → 将块与问题一起送入 GPT 生成答案。因此 Embeddings 的模型一致性很重要：建索引与检索必须使用同一模型（如均为 text-embedding-ada-002），否则向量空间不一致，检索效果会下降。
七、Moderation 与提示词配合
在 system 或 user 中明确「不要生成暴力、仇恨、自伤等违规内容」，可减少模型主动生成违规内容的概率；Moderation 对用户输入的审核可拦截恶意注入（如提示词注入），对模型输出的审核可兜底。两者结合形成「提示约束 + 事后审核」的双重保障，符合书中对安全与内容审核的强调。
八、Embeddings 与 Moderation 的调用成本
Embeddings 按 Token 计费，批量调用可摊薄单次成本；Moderation 有独立定价，调用频率高时需纳入成本预算。在客服、UGC 等场景，建议对用户输入必走 Moderation，对模型输出可按策略抽样或全量审核。
十、与书中第2.8节「其他OpenAI API和功能」的对应
本书第 2 章将 Embeddings API（文本向量化、相似度计算、RAG 基础）、Moderation API（内容安全审核、违规检测）与 Function Calling（下一节）并列。本节覆盖前两者：Embeddings 的调用示例、批量嵌入、相似度计算与 RAG 中的角色，对应书中「文本向量化、相似度、RAG 基础」；Moderation 的调用、类别说明与提示词配合，对应「内容安全审核、违规检测」。Function Calling 在 2.9 节单独讲解。学完 2.8 与 2.9，即可掌握书中「其他 API 和功能」的全部要点，为第 5 章 RAG 与 Agent 打下基础。
十二、Embeddings 与 Moderation 的典型集成位置
Embeddings：常见集成点包括（1）离线建库：将文档分块后批量调用 Embeddings API，写入向量库；（2）在线检索：用户提问时将 query 转为向量，在向量库中做相似度检索；（3）与 2.1 节 Token 结合：单次可传入多段文本，注意总 Token 上限。Moderation：常见集成点包括（1）网关或业务层对用户输入做审核，违规则拒绝或转人工；（2）对模型输出做审核，防止生成违规内容；（3）与 3.4 节提示词注入防御结合，对疑似注入的输入做 Moderation 或规则检测。书中「文本向量化、RAG 基础」与「内容安全审核」在本节已落实到调用方式与集成位置，便于在第 5、6 章中直接使用。
十一、小结
Embeddings 用于语义检索与 RAG；Moderation 用于内容安全。两者是生产级 LLM 应用的重要组件。掌握批量嵌入与 Moderation 的类别解读，可更好地集成到业务中。在实际项目中，Embeddings 常与 LlamaIndex、LangChain 等框架配合构建 RAG，Moderation 常与网关或业务层结合，在请求前后做双重审核。
十三、与 2.7 成本、第 5 章 RAG 的衔接
2.7 节成本：Embeddings 与 Moderation 均按调用计费，大批量建索引时 Embeddings 成本会累积。建议在 2.7 节的用量统计中单独统计 Embeddings/Moderation 的调用量与 Token，便于预算与优化。第 5 章 RAG：书中第 5 章「构建 RAG 系统」与 LlamaIndex 实战中，文档分块后的向量化即依赖 Embeddings API；本节掌握的 text-embedding-ada-002 调用与批量嵌入，是 5.4、5.5 节 RAG 索引构建的基础。学完本节即可在第 5 章中直接使用 Embeddings 建库与检索。
十四、Moderation 返回结构示例与业务处理建议
response.results[0] 包含 flagged（是否违规）与 categories（如 harassment、self-harm 等子类）。业务层可根据 flagged 直接拒绝或转人工；若需细分策略，可根据 categories 中为 True 的项做不同处理（如仅屏蔽某类、记录审计日志）。建议在接入层或业务层统一封装 Moderation 调用，对违规请求返回统一错误码与提示，与书中「内容安全审核」的落地一致。与 3.4 节提示词注入防御的配合：对用户输入做 Moderation 可辅助识别恶意注入或违规内容，再结合 3.4、3.5 节的输入过滤与防御性提示，形成「内容安全 + 注入防御」的双重保障。
下一节预告：2.9 OpenAI Function Calling函数调用完整实现教程
