企业官网建设流程全解析

AgentScope嵌入模型完整指南：10行代码搭出语义检索知识库

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope

做客服机器人时，用户问"怎么退款"，关键词搜不出任何文档——因为文档里写的是"退货流程"。AgentScope 嵌入模型（Embedding Model）把文本变成向量，让系统按语义相似度检索，"意思相近"就能命中，这是 RAG 类应用能跑通的第一步。

🎯 先给结论

一句话：嵌入模型把"读懂文字"这件事外包给向量，你只需把文档存进知识库、用自然语言问，相似内容自己排着队出来，不用再手写关键词匹配逻辑。

一次跑通：最小示例拿到检索结果

先装依赖：uv pip install "agentscope[rag]"，再配好环境变量DASHSCOPE_API_KEY。下面这段是核心流程的精简版，能跑通"入库 + 检索"一次完整循环（仓库里 examples/rag/index_and_search.py 是可直接执行的完整版，装好就能python examples/rag/index_and_search.py运行）：

from agentscope.credential import DashScopeCredential from agentscope.embedding import DashScopeEmbeddingModel from agentscope.rag import ApproxTokenChunker, KnowledgeBase, QdrantStore, TextParser store = QdrantStore(location=":memory:") async with store: model = DashScopeEmbeddingModel( credential=DashScopeCredential(api_key="sk-..."), model="text-embedding-v4", dimensions=1024) kb = KnowledgeBase(name="docs", description="产品文档", embedding_model=model, vector_store=store, collection="docs") chunks = await ApproxTokenChunker(chunk_size=256).chunk( await TextParser().parse(file=b"AgentScope是开源多智能体框架", filename="a.md")) await kb.insert_document(chunks) print(await kb.search(queries=["什么是AgentScope？"], top_k=2))

向量库这里用的是内存版 Qdrant，零配置；要持久化或换 Milvus Lite、MongoDB、Elasticsearch，只需替换store那一行，其余代码不动。

背后发生了什么：一句话怎么变成检索结果

把整个过程想成图书馆编目：

• 输入：文档先经过解析器（TextParser）拆成段落，再由ApproxTokenChunker切成固定大小的"块"，块是索引的最小单位；
• 处理：每个块发给嵌入模型，模型返回一个固定长度的数字列表（向量）。语义相近的块，向量在空间里靠得近。批量入库时框架会自动分批并发调用、失败重试，这些脏活都封装在 src/agentscope/embedding/ 的统一接口EmbeddingModelBase里；
• 输出：向量连同原文一起存进向量库。你提问时，查询句也被转成同一个模型的向量，库返回余弦相似度最高的前 k 个块——相似度就是"语义距离"的量化。

上手后必调的3个参数

向量维度怎么选

dimensions决定向量长度。text-embedding-v4支持 64～2048 档，默认 1024。维度越高表达越细，但存储和检索成本也越高。新手直接用 1024；短文本多的场景可以降到 512 省空间。注意一个硬约束：建索引和查询必须用同一个维度，向量库的 collection 按维度创建，中途换维度等于重建。

相似度阈值怎么调

kb.search(..., score_threshold=0.7)里的阈值控制"宁缺毋滥"还是"宁滥毋缺"。余弦相似度下，通用场景从 0.6～0.7 起步：结果里混入无关块就调高，总查不全就调低。不传该参数则返回前 k 条，不过滤。

让重复计算不再花钱

同一篇文档反复入库、同一段话反复嵌入，都是在为同样的结果付两次 API 费用。框架内置文件缓存，加一个参数即可：

from agentscope.embedding import FileEmbeddingCache # 初始化模型时传入 embedding_cache=FileEmbeddingCache(cache_dir="./.cache/embeddings")

命中缓存的请求不再走 API，还能通过max_file_number、max_cache_size限制缓存目录膨胀，实现细节见 src/agentscope/embedding/_file_cache.py。

选型建议：你的情况该选哪种

嵌入模型都挂在同一套接口下，切换只改初始化那几行。对照下面这张表挑：

判断顺序：先问数据能不能出网，再问内容语言，最后才比维度参数。多模态需求（图片、视频一起检索）可看 DashScope 的qwen*-vl-embedding系列，同一模型类会自动路由到多模态接口。

回头看，嵌入模型做的就一件事：把"理解语义"的成本从每次检索挪到一次向量化。跑通本文示例后，下一步建议把知识库挂到 Agent 上，让智能体自己决定何时检索，完整接法在 examples/rag/integrate_with_agent.py 里有两种模式（自动注入和工具调用）可以直接抄。

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope