DataHub 语义搜索 Embedding 提供商切换指南索引重建、模型维度对齐与全链路迁移实践【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本篇指南面向已经在 DataHub 中启用语义搜索Semantic Search的运维与数据平台工程师完整讲解如何在 OpenAI、AWS Bedrock、Cohere、Classical 等 Embedding 提供商之间安全迁移。读完后你将掌握停止服务 → 删除语义索引 → 更新提供商配置 → 重建索引 → 重新摄取 → 验证的完整迁移流程并能从源码层面理解模型键model key派生、向量维度校验和 GMS 摄取端/查询端双侧模型一致性这些容易踩坑的核心机制。为什么切换提供商必须删除并重建语义索引DataHub 的语义搜索基于 k-NN 向量检索摄取连接器Ingestion Connector在摄取时为文档生成嵌入向量并写入语义索引documentindex_v2_semanticGMS 在搜索时用同一模型生成查询向量再由 OpenSearch 的 k-NN 插件做余弦相似度检索。不同模型产生的向量在维度上不兼容——例如 OpenAItext-embedding-3-large输出 3072 维而 AWS Bedrock 的cohere.embed-english-v3输出 1024 维。OpenSearch 的 k-NN 字段在索引创建时就固定了向量维度因此切换提供商无法就地换模型唯一的正确路径是删除现有语义索引更新提供商与索引配置重启 GMS让系统更新任务System Update Job按新配置重建索引映射重新摄取全部文档用新模型重新生成所有嵌入。从源码结构看这一先删后建的设计还体现在索引清理逻辑中ESIndexBuilder.java 中专门处理了基础实体清理模式如datasetindex_v2_*会误匹配到datasetindex_v2_semantic的场景说明语义索引在索引生命周期管理中被当作一个独立、有状态的对象来维护——它的 mapping 状态与所配置的模型强绑定。首次配置语义搜索包括各提供商的完整配置项请参考 Semantic Search Configuration本文聚焦迁移这一场景。哪些场景需要这份指南从 OpenAI 切换到 AWS Bedrock或反向切换切换到另一个向量维度不同的模型从 Cohere 直连 API 切换到 AWS Bedrock 托管的 Cohere 模型切换进入或离开classical提供商或修改其hash-v1-dims宽度每种宽度都是一个独立的模型键提供商与模型参考提供商模型模型键Model Key维度OpenAItext-embedding-3-largetext_embedding_3_large3072OpenAItext-embedding-3-smalltext_embedding_3_small1536AWS Bedrockcohere.embed-english-v3cohere_embed_v31024Cohereembed-english-v3.0embed_english_v3_01024Classicalhash-v1-2048hash_v1_20482048重要模型键由模型名派生而来基本规则是将-和.替换为_。摄取连接器与 GMS 必须使用同一模型才能保证查询向量与文档向量在同一向量空间内。模型键派生的源码实现显式映射 兜底替换模型键不是简单的字符串替换。在 SemanticEntitySearchServiceFactory.java 中deriveModelEmbeddingKeyFromModelId被注释明确标注为模型键派生的唯一事实来源single source of truth它先做显式前缀匹配再做兜底替换// Cohere 原生模型embed-english-v3.0 等 // 必须先检查因为它们也匹配 embed-english-v3 模式 if (modelId.contains(embed-english-v3.0)) return embed_english_v3_0; if (modelId.contains(embed-multilingual-v3.0)) return embed_multilingual_v3_0; // AWS Bedrock 上的 Cohere 模型无 .0 后缀 if (modelId.contains(embed-english-v3)) return cohere_embed_v3; if (modelId.contains(embed-multilingual-v3)) return cohere_embed_multilingual_v3; // AWS Bedrock Titan 模型 if (modelId.contains(titan-embed-text-v1)) return amazon_titan_v1; if (modelId.contains(titan-embed-text-v2)) return amazon_titan_v2; // 兜底把特殊字符替换成下划线 return modelId.replace(-, _).replace(., _).replace(:, _);这里有一个迁移时极易混淆的细节Bedrock 的cohere.embed-english-v3与 Cohere 直连的embed-english-v3.0虽然模型相似但派生出两个不同的键cohere_embed_v3vsembed_english_v3_0。因此从 Cohere 直连切到 Bedrock或反之即使都是 1024 维、看起来是同一个模型索引中的嵌入字段名完全不同——旧文档的嵌入对新查询路径不可见必须重建索引并重新摄取。这正是该指南适用场景之一。模型键同时承担两个角色它是SemanticContentaspect 中embeddingsmap 的 key也是语义索引中的字段名。从源码结构看GMS 启动时就是用这个派生出的键去索引中定位嵌入字段SemanticEntitySearchServiceFactory.java 中的日志Derived modelEmbeddingKey... from providerType..., modelId...会打印该过程所以键不匹配会直接表现为查询无任何结果而不是报错。迁移步骤Step 1停止 DataHub 服务先停止 GMS 及所有摄取任务避免迁移期间有写入# Docker Compose docker stop datahub-gms # Kubernetes kubectl scale deployment datahub-gms --replicas0Step 2删除语义索引从 OpenSearch 中删除现有语义索引# 查看现有语义索引 curl -s http://localhost:9200/_cat/indices/*semantic*?v # 删除语义索引按需调整索引名 curl -X DELETE http://localhost:9200/documentindex_v2_semantic若删除前可能还需要回滚建议先备份该索引_snapshot或reindex到临时索引。Step 3更新提供商配置按新提供商更新配置各提供商的完整配置项Helm values 与环境变量两种形式见 Semantic Search Configuration。至少需要更新三处提供商类型EMBEDDING_PROVIDER_TYPEAPI 凭证API Key 或 IAM 角色/凭证链向量维度ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION必须与新模型输出一致各提供商在 application.yaml 中的默认值与对应环境变量type默认openaimaxCharacterLength默认 2048 字符embeddingProvider: type: ${EMBEDDING_PROVIDER_TYPE:openai} maxCharacterLength: ${EMBEDDING_PROVIDER_MAX_CHAR_LENGTH:2048} bedrock: awsRegion: ${BEDROCK_EMBEDDING_AWS_REGION:us-west-2} model: ${BEDROCK_EMBEDDING_MODEL:cohere.embed-english-v3} openai: apiKey: ${OPENAI_API_KEY:} model: ${OPENAI_EMBEDDING_MODEL:text-embedding-3-large} endpoint: ${OPENAI_EMBEDDING_ENDPOINT:https://api.openai.com/v1/embeddings} cohere: apiKey: ${COHERE_API_KEY:} model: ${COHERE_EMBEDDING_MODEL:embed-english-v3.0} endpoint: ${COHERE_EMBEDDING_ENDPOINT:https://api.cohere.ai/v1/embed}以环境变量方式切换的典型示例作用于datahub-gms服务改完需重启# 切换到 AWS Bedrock走 AWS SDK 默认凭证链无需 API Key EMBEDDING_PROVIDER_TYPEaws-bedrock BEDROCK_EMBEDDING_AWS_REGIONus-west-2 ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION1024 # 切换到 Cohere 直连 EMBEDDING_PROVIDER_TYPEcohere COHERE_API_KEYyour-cohere-api-key ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION1024从源码看GMS 侧由 EmbeddingProviderFactory.java 按type分支创建提供商实例当前支持aws-bedrock、openai、cohere、local、vertex_ai、onnx、classical七种类型未知类型会直接抛出Unsupported embedding provider type启动失败。工厂还对每个提供商做前置校验OpenAI / CohereAPI Key 为空即抛IllegalStateExceptionOpenAI API key is required when using openai embedding provider...所以Invalid API key类问题会表现为 GMS 启动失败而非查询时报错AWS Bedrock必须存在共享的defaultAwsCredentialsProviderBean且bedrock.awsRegion必填当 Bedrock 区域与 Pod 的AWS_REGION不一致时会记录跨区访问日志Classical除非显式设置CLASSICAL_EMBEDDING_ACKNOWLEDGE_LEXICAL_ONLYtrue否则 GMS 拒绝启动并校验模型键对应的semanticSearch.models条目存在、vectorDimension与宽度一致、spaceType为cosinesimil/cosine。Step 4更新索引模型映射如果使用application.yaml更新models段以匹配新提供商elasticsearch: entityIndex: semanticSearch: models: # 使用与新提供商匹配的模型键 text_embedding_3_large: vectorDimension: 3072 # 必须与模型输出一致 knnEngine: faiss spaceType: cosinesimil efConstruction: 128 m: 16或通过环境变量该变量驱动默认模型text_embedding_3_large的维度ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION3072仓库默认配置中 semanticSearch.models 已预置了多个常见模型条目包括text_embedding_3_large3072、nomic_embed_text768本地 Ollama 默认、gemini_embedding_001Vertex AI、snowflake_arctic_embed_s/snowflake_arctic_embed_lONNX 进程内推理、bge_base_en_v1_5以及hash_v1_2048Classical。如果你的新模型键尚未在其中需要手动补一条classical的hash_v1_2048条目则随版本内置无需额外添加。每个条目支持完整的 k-NN 调优参数详见 Semantic Search 配置指南参数说明常用取值vectorDimension向量维度必须与模型输出一致由模型决定knnEnginek-NN 引擎faiss推荐或nmslibfaissspaceType相似度度量cosinesimil文本推荐/l2/innerproductcosinesimilefConstructionHNSW 建图精度32–512开发 64 / 生产 128 / 高精度 256m每节点连接数4–64开发 8 / 生产 16 / 高精度 32注意classical提供商的向量是未归一化的整型计数工厂在启动时强制要求其spaceType精确等于cosinesimilOpenSearch或cosineElasticsearch否则抛出启动异常——这是为了防止宽度或度量不匹配退化成静默的空搜索结果。Step 5启动 DataHub重启 GMS系统更新任务会自动重建语义索引# Docker Compose docker start datahub-gms # Kubernetes kubectl scale deployment datahub-gms --replicas1系统更新任务在启动时自动执行流程为检测到语义索引缺失按新 Embedding 模型的 mapping 创建索引在 GMS 日志中记录进度。可用以下命令确认提供商被正确初始化# Docker Compose docker-compose logs datahub-gms | grep -i embedding # Kubernetes kubectl logs deployment/datahub-gms | grep -i embedding正常应看到类似Creating embedding provider with type: openai Initialized OpenAiEmbeddingProvider with modeltext-embedding-3-large若切换的是classical提供商还有额外的前置条件hash_v1_2048字段是由包含该版本的第一次 system-update 运行添加到索引的且运行 system-update 的进程本身也要带上语义搜索变量与CLASSICAL_EMBEDDING_ACKNOWLEDGE_LEXICAL_ONLYtrue显式确认GMS 之外的每个构建 Embedding 提供商的进程——如 Docker Compose 中的system-update服务和 MAE 消费者——都需要该确认否则拒绝启动。仅重启 GMS 不会补加该字段需要至少跑一次 system-update。Step 6重新摄取文档索引重建后重新摄取文档以生成新嵌入datahub ingest -c your-recipe.yaml关键约束摄取配方recipe也必须使用与 GMS 相同的 Embedding 模型。两侧分工如下上下文时机生成方配置位置文档嵌入摄取时Ingestion Connector摄取配方的embedding段查询嵌入搜索时GMSGMS 配置EMBEDDING_PROVIDER_TYPE等文档嵌入经由 MCPMetadata Change Proposal以semanticContentaspect 发出其embeddingsmap 以模型键为字段如embeddings.text_embedding_3_large必须与索引 mapping 中的键一致。以datahub-documents源为例见 datahub-documents 源文档source: type: datahub-documents config: # 从服务端拉取嵌入配置推荐自动与 GMS 对齐 embedding: {} # 或显式覆盖会与服务器校验不匹配会报错 # embedding: # provider: bedrock # bedrock / cohere / openai / onnx / classical # model: cohere.embed-english-v3 # model_embedding_key: cohere_embed_v3 # 必须与服务器一致最小配方示例source: type: datahub-documents config: {} sink: type: datahub-rest config: {}该源会自动连接 DataHub、从服务端拉取嵌入配置并实时处理文档。切换提供商后若配方仍沿用旧模型就会出现摄取端与查询端模型不一致表现为查询无结果见下文故障排查。Step 7验证# 检查索引是否存在且 mapping 正确 curl -s http://localhost:9200/documentindex_v2_semantic/_mapping?pretty | head -50 # 检查文档是否已有嵌入 curl -s http://localhost:9200/documentindex_v2_semantic/_search \ -H Content-Type: application/json \ -d {size: 1, _source: [urn, embeddings]} | head -30 # 通过 GraphQL 或 UI 测试语义搜索GraphQL 验证查询query SemanticSearch($input: SearchAcrossEntitiesInput!) { semanticSearchAcrossEntities(input: $input) { total searchResults { entity { urn type ... on Document { info { title } } } } } }{ input: { query: how to request data access, types: [DOCUMENT], start: 0, count: 10 } }也可以用聚合查询检查嵌入覆盖率with_embeddingsvswithout_embeddings两个过滤聚合字段名替换为你实际的模型键完整命令见 Semantic Search 配置指南的 Monitoring 一节。仓库内置的冒烟测试 test_classical_embedding_provider.py 演示了如何端到端验证摄取 → 嵌入 → kNN 检索链路可作为验证思路参考。故障排查No embeddings found切换后无嵌入原因文档是在切换提供商之前摄取的携带的是旧模型的嵌入。解决方案重新运行摄取用新提供商生成新嵌入。Dimension mismatch维度不匹配错误原因索引创建的向量维度与新模型的输出维度不一致如Dimension mismatch: expected 3072, got 1024。解决方案删除语义索引并让其重建即上文 Step 2–5同时把ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION与semanticSearch.models.key.vectorDimension都改为新模型的正确维度。Invalid API keyAPI 密钥无效原因API Key 未设置或设置错误。解决方案在 GMS 容器内核对环境变量docker exec datahub-gms env | grep -E OPENAI_API_KEY|COHERE_API_KEY从源码看Key 缺失时 EmbeddingProviderFactory 会在 Bean 创建阶段直接抛出IllegalStateException提示你设置OPENAI_API_KEY/COHERE_API_KEY环境变量或在application.yaml中配置embeddingProvider.provider.apiKey——因此若 GMS 能正常启动但报 key 无效重点检查 key 本身是否正确、是否有权限。查询无结果但文档存在原因摄取端与查询端的模型不一致。解决方案确认两侧使用同一个 Embedding 模型检查两处配置GMS 侧的提供商模型环境变量BEDROCK_EMBEDDING_MODEL、OPENAI_EMBEDDING_MODEL、COHERE_EMBEDDING_MODEL或CLASSICAL_EMBEDDING_MODEL摄取配方中的embedding配置含model_embedding_key最佳实践全链路同一模型确保摄取连接器与 GMS 使用完全相同的 Embedding 模型含模型键这是语义搜索正确性的第一前提。先在开发环境演练在生产之前先在 dev 环境完成一次提供商切换跑通删索引 → 重建 → 重摄取 → 验证全流程。为重摄取预留时间切换提供商意味着全量重新生成嵌入大数据量下可能耗时很长应纳入变更窗口规划。关注成本不同提供商计费方式不同OpenAI 与 Cohere 按 token/请求计费大规模重摄取会产生一次性 API 成本。删除索引前先备份保留语义索引快照以便必要时回滚。利用启动时校验GMS 工厂在启动阶段即完成提供商配置、维度与semanticSearch.models映射的校验如 classical 的宽度/度量校验因此迁移后先启动 GMS 并观察日志再开始摄取可以把配置错误拦截在最小数据面上。延伸阅读Semantic Search 总览架构、MCP 嵌入流程与冒烟测试Semantic Search 配置指南application.yaml高级参考、k-NN 调优与自定义提供商扩展Semantic Search 配置how-to各提供商的 Helm / 环境变量完整配置【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub 语义搜索 Embedding 提供商切换指南：索引重建、模型维度对齐与全链路迁移实践
DataHub 语义搜索 Embedding 提供商切换指南索引重建、模型维度对齐与全链路迁移实践【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本篇指南面向已经在 DataHub 中启用语义搜索Semantic Search的运维与数据平台工程师完整讲解如何在 OpenAI、AWS Bedrock、Cohere、Classical 等 Embedding 提供商之间安全迁移。读完后你将掌握停止服务 → 删除语义索引 → 更新提供商配置 → 重建索引 → 重新摄取 → 验证的完整迁移流程并能从源码层面理解模型键model key派生、向量维度校验和 GMS 摄取端/查询端双侧模型一致性这些容易踩坑的核心机制。为什么切换提供商必须删除并重建语义索引DataHub 的语义搜索基于 k-NN 向量检索摄取连接器Ingestion Connector在摄取时为文档生成嵌入向量并写入语义索引documentindex_v2_semanticGMS 在搜索时用同一模型生成查询向量再由 OpenSearch 的 k-NN 插件做余弦相似度检索。不同模型产生的向量在维度上不兼容——例如 OpenAItext-embedding-3-large输出 3072 维而 AWS Bedrock 的cohere.embed-english-v3输出 1024 维。OpenSearch 的 k-NN 字段在索引创建时就固定了向量维度因此切换提供商无法就地换模型唯一的正确路径是删除现有语义索引更新提供商与索引配置重启 GMS让系统更新任务System Update Job按新配置重建索引映射重新摄取全部文档用新模型重新生成所有嵌入。从源码结构看这一先删后建的设计还体现在索引清理逻辑中ESIndexBuilder.java 中专门处理了基础实体清理模式如datasetindex_v2_*会误匹配到datasetindex_v2_semantic的场景说明语义索引在索引生命周期管理中被当作一个独立、有状态的对象来维护——它的 mapping 状态与所配置的模型强绑定。首次配置语义搜索包括各提供商的完整配置项请参考 Semantic Search Configuration本文聚焦迁移这一场景。哪些场景需要这份指南从 OpenAI 切换到 AWS Bedrock或反向切换切换到另一个向量维度不同的模型从 Cohere 直连 API 切换到 AWS Bedrock 托管的 Cohere 模型切换进入或离开classical提供商或修改其hash-v1-dims宽度每种宽度都是一个独立的模型键提供商与模型参考提供商模型模型键Model Key维度OpenAItext-embedding-3-largetext_embedding_3_large3072OpenAItext-embedding-3-smalltext_embedding_3_small1536AWS Bedrockcohere.embed-english-v3cohere_embed_v31024Cohereembed-english-v3.0embed_english_v3_01024Classicalhash-v1-2048hash_v1_20482048重要模型键由模型名派生而来基本规则是将-和.替换为_。摄取连接器与 GMS 必须使用同一模型才能保证查询向量与文档向量在同一向量空间内。模型键派生的源码实现显式映射 兜底替换模型键不是简单的字符串替换。在 SemanticEntitySearchServiceFactory.java 中deriveModelEmbeddingKeyFromModelId被注释明确标注为模型键派生的唯一事实来源single source of truth它先做显式前缀匹配再做兜底替换// Cohere 原生模型embed-english-v3.0 等 // 必须先检查因为它们也匹配 embed-english-v3 模式 if (modelId.contains(embed-english-v3.0)) return embed_english_v3_0; if (modelId.contains(embed-multilingual-v3.0)) return embed_multilingual_v3_0; // AWS Bedrock 上的 Cohere 模型无 .0 后缀 if (modelId.contains(embed-english-v3)) return cohere_embed_v3; if (modelId.contains(embed-multilingual-v3)) return cohere_embed_multilingual_v3; // AWS Bedrock Titan 模型 if (modelId.contains(titan-embed-text-v1)) return amazon_titan_v1; if (modelId.contains(titan-embed-text-v2)) return amazon_titan_v2; // 兜底把特殊字符替换成下划线 return modelId.replace(-, _).replace(., _).replace(:, _);这里有一个迁移时极易混淆的细节Bedrock 的cohere.embed-english-v3与 Cohere 直连的embed-english-v3.0虽然模型相似但派生出两个不同的键cohere_embed_v3vsembed_english_v3_0。因此从 Cohere 直连切到 Bedrock或反之即使都是 1024 维、看起来是同一个模型索引中的嵌入字段名完全不同——旧文档的嵌入对新查询路径不可见必须重建索引并重新摄取。这正是该指南适用场景之一。模型键同时承担两个角色它是SemanticContentaspect 中embeddingsmap 的 key也是语义索引中的字段名。从源码结构看GMS 启动时就是用这个派生出的键去索引中定位嵌入字段SemanticEntitySearchServiceFactory.java 中的日志Derived modelEmbeddingKey... from providerType..., modelId...会打印该过程所以键不匹配会直接表现为查询无任何结果而不是报错。迁移步骤Step 1停止 DataHub 服务先停止 GMS 及所有摄取任务避免迁移期间有写入# Docker Compose docker stop datahub-gms # Kubernetes kubectl scale deployment datahub-gms --replicas0Step 2删除语义索引从 OpenSearch 中删除现有语义索引# 查看现有语义索引 curl -s http://localhost:9200/_cat/indices/*semantic*?v # 删除语义索引按需调整索引名 curl -X DELETE http://localhost:9200/documentindex_v2_semantic若删除前可能还需要回滚建议先备份该索引_snapshot或reindex到临时索引。Step 3更新提供商配置按新提供商更新配置各提供商的完整配置项Helm values 与环境变量两种形式见 Semantic Search Configuration。至少需要更新三处提供商类型EMBEDDING_PROVIDER_TYPEAPI 凭证API Key 或 IAM 角色/凭证链向量维度ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION必须与新模型输出一致各提供商在 application.yaml 中的默认值与对应环境变量type默认openaimaxCharacterLength默认 2048 字符embeddingProvider: type: ${EMBEDDING_PROVIDER_TYPE:openai} maxCharacterLength: ${EMBEDDING_PROVIDER_MAX_CHAR_LENGTH:2048} bedrock: awsRegion: ${BEDROCK_EMBEDDING_AWS_REGION:us-west-2} model: ${BEDROCK_EMBEDDING_MODEL:cohere.embed-english-v3} openai: apiKey: ${OPENAI_API_KEY:} model: ${OPENAI_EMBEDDING_MODEL:text-embedding-3-large} endpoint: ${OPENAI_EMBEDDING_ENDPOINT:https://api.openai.com/v1/embeddings} cohere: apiKey: ${COHERE_API_KEY:} model: ${COHERE_EMBEDDING_MODEL:embed-english-v3.0} endpoint: ${COHERE_EMBEDDING_ENDPOINT:https://api.cohere.ai/v1/embed}以环境变量方式切换的典型示例作用于datahub-gms服务改完需重启# 切换到 AWS Bedrock走 AWS SDK 默认凭证链无需 API Key EMBEDDING_PROVIDER_TYPEaws-bedrock BEDROCK_EMBEDDING_AWS_REGIONus-west-2 ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION1024 # 切换到 Cohere 直连 EMBEDDING_PROVIDER_TYPEcohere COHERE_API_KEYyour-cohere-api-key ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION1024从源码看GMS 侧由 EmbeddingProviderFactory.java 按type分支创建提供商实例当前支持aws-bedrock、openai、cohere、local、vertex_ai、onnx、classical七种类型未知类型会直接抛出Unsupported embedding provider type启动失败。工厂还对每个提供商做前置校验OpenAI / CohereAPI Key 为空即抛IllegalStateExceptionOpenAI API key is required when using openai embedding provider...所以Invalid API key类问题会表现为 GMS 启动失败而非查询时报错AWS Bedrock必须存在共享的defaultAwsCredentialsProviderBean且bedrock.awsRegion必填当 Bedrock 区域与 Pod 的AWS_REGION不一致时会记录跨区访问日志Classical除非显式设置CLASSICAL_EMBEDDING_ACKNOWLEDGE_LEXICAL_ONLYtrue否则 GMS 拒绝启动并校验模型键对应的semanticSearch.models条目存在、vectorDimension与宽度一致、spaceType为cosinesimil/cosine。Step 4更新索引模型映射如果使用application.yaml更新models段以匹配新提供商elasticsearch: entityIndex: semanticSearch: models: # 使用与新提供商匹配的模型键 text_embedding_3_large: vectorDimension: 3072 # 必须与模型输出一致 knnEngine: faiss spaceType: cosinesimil efConstruction: 128 m: 16或通过环境变量该变量驱动默认模型text_embedding_3_large的维度ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION3072仓库默认配置中 semanticSearch.models 已预置了多个常见模型条目包括text_embedding_3_large3072、nomic_embed_text768本地 Ollama 默认、gemini_embedding_001Vertex AI、snowflake_arctic_embed_s/snowflake_arctic_embed_lONNX 进程内推理、bge_base_en_v1_5以及hash_v1_2048Classical。如果你的新模型键尚未在其中需要手动补一条classical的hash_v1_2048条目则随版本内置无需额外添加。每个条目支持完整的 k-NN 调优参数详见 Semantic Search 配置指南参数说明常用取值vectorDimension向量维度必须与模型输出一致由模型决定knnEnginek-NN 引擎faiss推荐或nmslibfaissspaceType相似度度量cosinesimil文本推荐/l2/innerproductcosinesimilefConstructionHNSW 建图精度32–512开发 64 / 生产 128 / 高精度 256m每节点连接数4–64开发 8 / 生产 16 / 高精度 32注意classical提供商的向量是未归一化的整型计数工厂在启动时强制要求其spaceType精确等于cosinesimilOpenSearch或cosineElasticsearch否则抛出启动异常——这是为了防止宽度或度量不匹配退化成静默的空搜索结果。Step 5启动 DataHub重启 GMS系统更新任务会自动重建语义索引# Docker Compose docker start datahub-gms # Kubernetes kubectl scale deployment datahub-gms --replicas1系统更新任务在启动时自动执行流程为检测到语义索引缺失按新 Embedding 模型的 mapping 创建索引在 GMS 日志中记录进度。可用以下命令确认提供商被正确初始化# Docker Compose docker-compose logs datahub-gms | grep -i embedding # Kubernetes kubectl logs deployment/datahub-gms | grep -i embedding正常应看到类似Creating embedding provider with type: openai Initialized OpenAiEmbeddingProvider with modeltext-embedding-3-large若切换的是classical提供商还有额外的前置条件hash_v1_2048字段是由包含该版本的第一次 system-update 运行添加到索引的且运行 system-update 的进程本身也要带上语义搜索变量与CLASSICAL_EMBEDDING_ACKNOWLEDGE_LEXICAL_ONLYtrue显式确认GMS 之外的每个构建 Embedding 提供商的进程——如 Docker Compose 中的system-update服务和 MAE 消费者——都需要该确认否则拒绝启动。仅重启 GMS 不会补加该字段需要至少跑一次 system-update。Step 6重新摄取文档索引重建后重新摄取文档以生成新嵌入datahub ingest -c your-recipe.yaml关键约束摄取配方recipe也必须使用与 GMS 相同的 Embedding 模型。两侧分工如下上下文时机生成方配置位置文档嵌入摄取时Ingestion Connector摄取配方的embedding段查询嵌入搜索时GMSGMS 配置EMBEDDING_PROVIDER_TYPE等文档嵌入经由 MCPMetadata Change Proposal以semanticContentaspect 发出其embeddingsmap 以模型键为字段如embeddings.text_embedding_3_large必须与索引 mapping 中的键一致。以datahub-documents源为例见 datahub-documents 源文档source: type: datahub-documents config: # 从服务端拉取嵌入配置推荐自动与 GMS 对齐 embedding: {} # 或显式覆盖会与服务器校验不匹配会报错 # embedding: # provider: bedrock # bedrock / cohere / openai / onnx / classical # model: cohere.embed-english-v3 # model_embedding_key: cohere_embed_v3 # 必须与服务器一致最小配方示例source: type: datahub-documents config: {} sink: type: datahub-rest config: {}该源会自动连接 DataHub、从服务端拉取嵌入配置并实时处理文档。切换提供商后若配方仍沿用旧模型就会出现摄取端与查询端模型不一致表现为查询无结果见下文故障排查。Step 7验证# 检查索引是否存在且 mapping 正确 curl -s http://localhost:9200/documentindex_v2_semantic/_mapping?pretty | head -50 # 检查文档是否已有嵌入 curl -s http://localhost:9200/documentindex_v2_semantic/_search \ -H Content-Type: application/json \ -d {size: 1, _source: [urn, embeddings]} | head -30 # 通过 GraphQL 或 UI 测试语义搜索GraphQL 验证查询query SemanticSearch($input: SearchAcrossEntitiesInput!) { semanticSearchAcrossEntities(input: $input) { total searchResults { entity { urn type ... on Document { info { title } } } } } }{ input: { query: how to request data access, types: [DOCUMENT], start: 0, count: 10 } }也可以用聚合查询检查嵌入覆盖率with_embeddingsvswithout_embeddings两个过滤聚合字段名替换为你实际的模型键完整命令见 Semantic Search 配置指南的 Monitoring 一节。仓库内置的冒烟测试 test_classical_embedding_provider.py 演示了如何端到端验证摄取 → 嵌入 → kNN 检索链路可作为验证思路参考。故障排查No embeddings found切换后无嵌入原因文档是在切换提供商之前摄取的携带的是旧模型的嵌入。解决方案重新运行摄取用新提供商生成新嵌入。Dimension mismatch维度不匹配错误原因索引创建的向量维度与新模型的输出维度不一致如Dimension mismatch: expected 3072, got 1024。解决方案删除语义索引并让其重建即上文 Step 2–5同时把ELASTICSEARCH_SEMANTIC_VECTOR_DIMENSION与semanticSearch.models.key.vectorDimension都改为新模型的正确维度。Invalid API keyAPI 密钥无效原因API Key 未设置或设置错误。解决方案在 GMS 容器内核对环境变量docker exec datahub-gms env | grep -E OPENAI_API_KEY|COHERE_API_KEY从源码看Key 缺失时 EmbeddingProviderFactory 会在 Bean 创建阶段直接抛出IllegalStateException提示你设置OPENAI_API_KEY/COHERE_API_KEY环境变量或在application.yaml中配置embeddingProvider.provider.apiKey——因此若 GMS 能正常启动但报 key 无效重点检查 key 本身是否正确、是否有权限。查询无结果但文档存在原因摄取端与查询端的模型不一致。解决方案确认两侧使用同一个 Embedding 模型检查两处配置GMS 侧的提供商模型环境变量BEDROCK_EMBEDDING_MODEL、OPENAI_EMBEDDING_MODEL、COHERE_EMBEDDING_MODEL或CLASSICAL_EMBEDDING_MODEL摄取配方中的embedding配置含model_embedding_key最佳实践全链路同一模型确保摄取连接器与 GMS 使用完全相同的 Embedding 模型含模型键这是语义搜索正确性的第一前提。先在开发环境演练在生产之前先在 dev 环境完成一次提供商切换跑通删索引 → 重建 → 重摄取 → 验证全流程。为重摄取预留时间切换提供商意味着全量重新生成嵌入大数据量下可能耗时很长应纳入变更窗口规划。关注成本不同提供商计费方式不同OpenAI 与 Cohere 按 token/请求计费大规模重摄取会产生一次性 API 成本。删除索引前先备份保留语义索引快照以便必要时回滚。利用启动时校验GMS 工厂在启动阶段即完成提供商配置、维度与semanticSearch.models映射的校验如 classical 的宽度/度量校验因此迁移后先启动 GMS 并观察日志再开始摄取可以把配置错误拦截在最小数据面上。延伸阅读Semantic Search 总览架构、MCP 嵌入流程与冒烟测试Semantic Search 配置指南application.yaml高级参考、k-NN 调优与自定义提供商扩展Semantic Search 配置how-to各提供商的 Helm / 环境变量完整配置【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考