Swirl Search项目扩展开发教程：从SearchProvider到ResultProcessor全流程指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00545/article/details/148758747

Swirl Search项目扩展开发教程：从SearchProvider到ResultProcessor全流程指南

swirl-search Swirl is open-source software that uses AI to simultaneously search multiple content and data sources, finds the best results using a reader LLM, then prompts Generative AI, enabling you to get answers from your own data. 项目地址: https://gitcode.com/gh_mirrors/sw/swirl-search

前言

Swirl Search作为一个强大的搜索聚合平台，其核心优势在于可扩展性。本教程将深入讲解如何扩展Swirl Search功能，包括创建SearchProvider、开发Connector、实现QueryProcessor和ResultProcessor等核心组件。通过本教程，您将掌握Swirl Search的完整扩展开发流程。

基础概念

在开始扩展开发前，需要理解几个核心概念：

SearchProvider：搜索源的配置实例，定义了如何连接和查询特定数据源
Connector：实际执行搜索的组件，处理与数据源的通信
QueryProcessor：查询处理组件，用于修改或增强搜索查询
ResultProcessor：结果处理组件，用于处理和转换搜索结果

第一部分：创建SearchProvider

1.1 准备工作

在创建SearchProvider前，需要确认：

目标数据源是否已有支持的Connector
数据源的API接口文档
认证方式（如API密钥、OAuth等）

1.2 配置SearchProvider

以配置一个返回JSON的REST API为例：

{
    "name": "示例API搜索",
    "connector": "RequestsGet",
    "url": "https://api.example.com/search",
    "query_template": "{url}?query={query_string}",
    "query_mappings": "PAGE=page=RESULT_INDEX",
    "response_mappings": "FOUND=total_results,RETRIEVED=results_count,RESULTS=items",
    "result_mappings": "title=name,body=description,url=link,date_published=created_at",
    "credentials": "api_key=your-api-key-here",
    "tags": ["example"]
}

1.3 关键配置解析

query_template：定义查询URL模板，{query_string}会被实际查询替换
query_mappings：分页和排序参数映射
response_mappings：指定如何从响应中提取结果总数和结果列表
result_mappings：定义如何将源数据字段映射到Swirl标准字段

1.4 测试与验证

添加SearchProvider后，建议：

使用Galaxy UI进行测试
检查返回结果是否符合预期
验证所有映射是否正确工作

第二部分：开发自定义Connector

2.1 何时需要自定义Connector

当遇到以下情况时需要考虑开发自定义Connector：

数据源使用非标准协议
需要特殊认证方式
返回数据格式无法通过现有Connector处理

2.2 Connector开发步骤

创建Python文件：swirl/connectors/my_connector.py
继承基础Connector类
实现核心方法

from swirl.connectors.connector import Connector

class MyCustomConnector(Connector):
    def __init__(self, provider_id, search_id, update, request_id=''):
        super().__init__(provider_id, search_id, update, request_id)
        # 初始化代码
        
    def execute_search(self, session=None):
        # 实现搜索逻辑
        pass
        
    def normalize_response(self):
        # 标准化响应数据
        pass

2.3 关键方法实现

execute_search方法

负责：

建立与数据源的连接
发送查询请求
处理响应

normalize_response方法

负责：

将原始响应转换为Swirl标准格式
设置结果计数(found/retrieved)

2.4 注册Connector

在swirl/connectors/__init__.py中添加：

from swirl.connectors.my_connector import MyCustomConnector

第三部分：实现QueryProcessor

3.1 QueryProcessor类型

Pre-Query Processor：在所有SearchProvider前执行
Query Processor：针对单个SearchProvider执行

3.2 开发步骤

创建处理器文件：swirl/processors/my_query_processor.py
继承QueryProcessor基类
实现process方法

from swirl.processors.query_processor import QueryProcessor

class MyQueryProcessor(QueryProcessor):
    type = 'MyQueryProcessor'
    
    def process(self):
        # 查询处理逻辑
        modified_query = self.query_string.upper()  # 示例：转为大写
        return modified_query

3.3 注册处理器

在swirl/processors/__init__.py中导入
添加到模型CHOICES中
设置默认处理器列表

第四部分：开发ResultProcessor

4.1 常见应用场景

结果数据清洗
字段标准化
结果过滤
相关性计算

4.2 开发步骤

from swirl.processors.result_processor import ResultProcessor

class MyResultProcessor(ResultProcessor):
    type = 'MyResultProcessor'
    
    def process(self):
        if not self.results:
            return 0
            
        updated = 0
        for item in self.results:
            # 处理逻辑
            item['processed'] = True
            updated += 1
            
        self.processed_results = self.results
        return updated