Vespa自定义ORgram搜索链无法识别问题求助

问题背景 #

尝试在java/ai/vespa/example路径下实现自定义OrNGramSearcher，将原生NGramSearcher的AND组合逻辑改为OR，同时在services.xml中配置新的搜索链，但查询时提示**No search chain named 'ORgram' was found**，原生NGramSearcher未被排除，自定义搜索器也未生效。

自定义搜索器代码 #

package ai.vespa.example;

import com.yahoo.search.Query;
import com.yahoo.prelude.query.CompositeItem;
import com.yahoo.prelude.query.OrItem;
import com.yahoo.prelude.query.HasIndexItem;
import com.yahoo.search.querytransform.NGramSearcher;
import com.yahoo.language.Linguistics;

public class OrNGramSearcher extends NGramSearcher {

    public OrNGramSearcher(Linguistics linguistics) {
        super(linguistics);
    }

    @Override
    protected CompositeItem createGramRoot(HasIndexItem term, Query query) {
        return new OrItem();
    }

}

配置的services.xml片段 #

<search>
    <chain id='ORgram' inherits='vespa' excludes='com.yahoo.search.querytransform.NGramSearcher'>
        <searcher bundle='gram-searcher' id='ai.vespa.examples.OrNGramSearcher'/>
    </chain>
</search>

报错信息 #

"message": "No search chain named 'ORgram' was found"

排查与解决步骤 #

1. 确认services.xml位置正确性 #

services.xml必须放在Vespa应用的**src/main/application/**目录下（而非bundle模块的目录中），这是Vespa加载应用配置的默认路径。如果是多模块Maven项目，需确保该文件位于负责打包应用包的模块中。

2. 验证bundle打包与部署 #

• 执行mvn clean package重新打包，检查target/application.zip中是否包含自定义搜索器的class文件，以及services.xml是否被正确打包进应用包。
• 执行vespa deploy target/application.zip重新部署应用，确保新配置和代码生效。

3. 检查搜索链配置语法与正确性 #

• 确认excludes属性中的类路径准确：原生NGramSearcher的类路径com.yahoo.search.querytransform.NGramSearcher在当前Vespa版本中是否有效（不同版本类路径可能有变更，可通过Vespa官方文档确认）。
• 检查XML标签的拼写和闭合：确保chain标签的id、inherits、excludes属性无拼写错误，标签结构完整无语法问题。

4. 确认查询时搜索链的指定方式 #

查询时必须显式指定使用ORgram搜索链：

• HTTP查询示例：http://<vespa-host>:<port>/search/?query=xxx&searchChain=ORgram
• 程序中通过Query对象设置：query.getModel().setSearchChain("ORgram");

5. 检查Vespa日志定位问题 #

使用vespa-logfmt命令查看Vespa服务日志，搜索与搜索链加载、bundle加载相关的错误信息，例如：

• bundle找不到或加载失败
• 自定义搜索器类加载异常
• 搜索链配置解析错误

6. 确认Maven依赖与bundle配置 #

• 确保pom.xml中引入了正确的Vespa依赖，版本与集群版本一致：

<dependency>
    <groupId>com.yahoo.vespa</groupId>
    <artifactId>searchlib</artifactId>
    <version>${vespa.version}</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.yahoo.vespa</groupId>
    <artifactId>linguistics</artifactId>
    <version>${vespa.version}</version>
    <scope>provided</scope>
</dependency>

• 确认pom.xml的artifactId与services.xml中bundle属性值（gram-searcher）完全一致。

内容的提问来源于stack exchange，提问作者QCoder