Skywork Embedding模型向量检索权威指南
使用Skywork Embedding模型时，有几个关键点需要提前确认：必须通过API调用，无法离线使用；中文文档需要按照语义段落切分，过滤掉低信息密度块，并添加元数据；向量库要设置cosine距离并归一化，相似度阈值建议在0.85左右。
如果你正打算用Skywork AI的Embedding模型把文档转成向量、存入向量库、然后做语义检索，很可能卡在模型调用方式、中文分块策略或相似度阈值设置这几个环节上。别急，下面逐一拆解。
确认Skywork Embedding模型是否可用
访问 https://skywork.ai/embedding ，先看一眼页面右上角的“Status”标签。如果显示绿色“Online”，说明服务正常；如果是灰色“Maintenance”或红色“Offline”，那就得另寻出路——改用本地部署方案。
需要特别提醒的是：Skywork官方并未开源Embedding模型权重，所有调用必须走其API接口，无法离线加载模型文件。
调用Skywork API生成文本向量
方法一：用curl命令快速验证
打开终端，执行以下命令即可（记得把YOUR_API_KEY换成你自己的密钥）：
curl -X POST "https://api.skywork.ai/v1/embeddings" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "今天天气不错", "model": "skywork-embedding-v2"}'方法二：用Python脚本批量处理
先装个依赖：pip install requests
然后写个脚本,embed_skywork.py：
import requests
def get_skywork_embedding(text):
url = "https://api.skywork.ai/v1/embeddings"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {"input": text, "model": "skywork-embedding-v2"}
res = requests.post(url, headers=headers, json=data)
return res.json()["data"][0]["embedding"]
vec = get_skywork_embedding("向量检索比关键词搜索更懂用户意图")
print(len(vec)) # 应输出1024操作起来其实很简单，直接把文件拖进去就行。但有一点要注意：单次请求的input字段最大支持8192个字符，超长文本必须先切块再分别调用。
中文文档切块与向量化最佳实践
第一步：按语义段落切分，而不是按固定字数
对于PDF或Word文档，推荐先用PaddleOCR-VL或PP-StructureV3解析出标题、正文、列表、表格等结构单元。然后以“标题+其下所有正文段”为一块，这样能有效避免跨章节割裂上下文。
第二步：过滤低信息密度块
这类内容可以直接丢弃：纯页眉页脚、重复的版权声明、空白行超过3行的段落。而包含动词、名词短语、数字指标的句子，比如“Q3营收同比增长23.6%”，必须单独成块保留。像“详见附录”这种套话，直接删掉就好。
第三步：对每块添加元数据标签
在向量入库时，同步写入source_file、page_number、section_title三个字段。后续检索时就可以加filter条件了，比如只查《2025产品白皮书》第12页的技术参数部分。
构建向量库并执行语义检索
用ChromaDB（适合轻量场景）或Milvus（适合高并发）来存储向量：
pip install chromadbimport chromadb
client = chromadb.PersistentClient(path="./skywork_db")
collection = client.create_collection(name="tech_docs", metadata={"hnsw:space": "cosine"})插入向量时，务必设置normalize_embeddings=True参数，否则余弦相似度计算结果会失真。
执行检索的代码也很直观：
query_vec = get_skywork_embedding("如何配置RAG流水线")
results = collection.query(
query_embeddings=[query_vec],
n_results=5,
where={"source_file": {"$eq": "rag_guide.pdf"}}
)
for i, doc in enumerate(results["documents"][0]):
print(f"Top{i+1}: {doc[:100]}...")最后再强调一句：Skywork-embedding-v2默认输出已经归一化的1024维向量，创建collection时一定要把hnsw:space指定为cosine，别用l2。
调试检索效果的三个关键阈值
方法一：查看原始相似度分数
collection.query()返回的结果中包含distances字段，值域是[0,2]。0表示完全相同，大于1.2基本就没什么语义关联了。
方法二：动态调整n_results数量
先设n_results=10，人工检查前5条是否相关。如果第4条开始就出现无关内容，说明阈值应该卡在0.85左右。
方法三：用测试集跑召回率
准备20个标准问句和对应的正确文档ID，构成黄金标准集。批量检索后统计“返回结果包含正确ID”的比例。如果低于75%，就需要重新切块或换模型了。