千问系列中qwen2-embedding和qwen2.5-embedding是专为语义搜索优化的embedding模型，需通过hugging face/modelscope确认支持、用sentence-transformers加载、构建faiss/annoy索引、统一分词截断策略，并在mteb-chinese等基准上评估ndcg@10等指标。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
千问系列模型中部分版本提供了专门优化的 embedding 模型，专为语义相似度计算与向量检索任务设计。以下是适用于语义搜索的 embedding 模型使用方法及相关配置要点：
一、确认模型是否支持 embedding 输出
千问的 embedding 模型需明确区分于通用语言模型（如 Qwen2、Qwen3），其输出为固定维度稠密向量，不生成文本。官方发布的 Qwen2-Embedding 和 Qwen2.5-Embedding 均经过对比学习微调，适配中文语义匹配任务。
1、访问 Hugging Face 或 ModelScope 平台，搜索模型名称，确认仓库描述中包含 “embedding”、“text-embedding” 或 “dense retrieval” 字样。
2、检查模型 card 中是否提供 get_text_embedding() 或 encode() 接口示例。
3、验证输入文本经模型处理后是否返回 shape 为 (1, D) 的 float32 张量，其中 D 通常为 1024 或 768。
二、使用 Sentence-Transformers 加载本地模型
若已下载模型权重，可通过 sentence-transformers 库进行标准化加载，确保 tokenization 与 pooling 方式与训练一致，避免语义向量偏移。
1、执行 pip install sentence-transformers 安装依赖库。
2、调用 SentenceTransformer("path/to/qwen2-embedding") 初始化模型实例。
3、传入中文查询句与文档句列表至 model.encode()，获取归一化后的嵌入向量。
三、构建 FAISS 或 Annoy 索引进行快速检索
语义搜索依赖高效近似最近邻（ANN）算法，原始 embedding 向量需导入专用索引结构以支撑毫秒级响应。
1、将全部文档 embedding 向量堆叠为 numpy 数组，shape 为 (N, D)。
2、使用 faiss.IndexFlatIP(D) 创建内积索引（要求向量已单位归一化）。
3、调用 index.add(vectors) 加载全部向量，后续通过 index.search(query_vector, k=10) 获取 Top-K 相似文档 ID。
四、对齐 query 与 document 的分词与截断策略
Qwen embedding 模型对输入长度敏感，query 与 document 若采用不同 max_length 或 padding 方式，会导致向量空间错位，显著降低召回率。
1、统一设置 max_length=512（Qwen2-Embedding 默认最大上下文）。
2、对超长文本采用首尾截断（head+tail），禁用滑动窗口截断，防止关键语义片段丢失。
3、确保 query 与 document 均经相同 tokenizer 处理，且不启用特殊 prompt 模板（如 “Query: … Document: …”）。
五、评估语义匹配质量需使用标准 benchmark
仅凭余弦相似度数值无法判断 embedding 效果优劣，必须在权威中文检索数据集上量化指标。
1、在 MTEB-Chinese 子集（如 T2Ranking、CMNLI-STS）上运行 zero-shot 评估脚本。
2、关注 NDCG@10 与 MAP@100 两项核心指标，Qwen2.5-Embedding 在 T2Ranking 上公开结果为 0.421 NDCG@10。
3、对比基线模型（如 bge-m3、multilingual-e5-large）在同一测试集下的分数，确认相对优势区间。
