扩展现有搜索和查询功能

关于查询扩展器和评分函数扩展的详细信息

RediSearch 支持扩展机制，就像 Redis 支持模块一样。目前 API 非常精简，并且尚不支持在运行中的服务器上动态加载扩展。扩展必须使用 C 语言（或具有 C 语言接口的语言）编写，并编译成可以在启动时加载的动态库。

目前有两种扩展 API：

  1. 查询扩展器，其作用是扩展查询 token（即词干提取器）。
  2. 评分函数，其作用是在查询时对搜索结果进行排序。

注册和加载扩展

扩展应编译为动态库文件（例如，.so 文件），并在初始化期间加载到 RediSearch 模块中。

编译

Extensions should be compiled and linked as dynamic libraries. An example Makefile for an extension [can be found here](https://github.com/RediSearch/RediSearch/blob/master/tests/ctests/ext-example/Makefile). 

That folder also contains an example extension that is used for testing and can be taken as a skeleton for implementing your own extension.

加载

Loading an extension is done by appending `EXTLOAD {path/to/ext.so}` after the `loadmodule` configuration directive when loading the RediSearch module. For example:

```sh
$ redis-server --loadmodule ./redisearch.so EXTLOAD ./ext/my_extension.so
```

This causes the RediSearch module to automatically load the extension and register its expanders and scorers.

初始化扩展

扩展的入口点是具有以下签名的函数：

int RS_ExtensionInit(RSExtensionCtx *ctx);

加载扩展时，RediSearch 会查找并调用此函数。此函数负责注册和初始化扩展器和评分器。

错误时应返回 REDISEARCH_ERR，成功时应返回 REDISEARCH_OK。

示例初始化函数

#include <redisearch.h> //must be in the include path

int RS_ExtensionInit(RSExtensionCtx *ctx) {

  /* Register  a scoring function with an alias my_scorer and no special private data and free function */
  if (ctx->RegisterScoringFunction("my_scorer", MyCustomScorer, NULL, NULL) == REDISEARCH_ERR) {
    return REDISEARCH_ERR;
  }

  /* Register a query expander  */
  if (ctx->RegisterQueryExpander("my_expander", MyExpander, NULL, NULL) ==
      REDISEARCH_ERR) {
    return REDISEARCH_ERR;
  }

  return REDISEARCH_OK;
}

调用你的自定义函数

执行查询时，你可以通过指定给定别名的 SCORER 或 EXPANDER 参数来使用你的评分器或扩展器。例如：

FT.SEARCH my_index "foo bar" EXPANDER my_expander SCORER my_scorer

注意：扩展器和评分器别名是区分大小写的。

查询扩展器 API

仅支持基本的查询扩展，一次一个 token。扩展器可以决定将任何给定的 token 扩展为任意数量的 token，这些 token 将在查询时合并。

扩展器的 API 如下：

#include <redisearch.h> //must be in the include path

void MyQueryExpander(RSQueryExpanderCtx *ctx, RSToken *token) {
    ...
}

RSQueryExpanderCtx

RSQueryExpanderCtx 是一个上下文，包含扩展的私有数据以及一个用于扩展查询的回调方法。其定义如下：

typedef struct RSQueryExpanderCtx {

  /* Opaque query object used internally by the engine, and should not be accessed */
  struct RSQuery *query;

  /* Opaque query node object used internally by the engine, and should not be accessed */
  struct RSQueryNode **currentNode;

  /* Private data of the extension, set on extension initialization */
  void *privdata;

  /* The language of the query, defaults to "english" */
  const char *language;

  /* ExpandToken allows the user to add an expansion of the token in the query, that will be
   * union-merged with the given token in query time. str is the expanded string, len is its length,
   * and flags is a 32 bit flag mask that can be used by the extension to set private information on
   * the token */
  void (*ExpandToken)(struct RSQueryExpanderCtx *ctx, const char *str, size_t len,
                      RSTokenFlags flags);

  /* SetPayload allows the query expander to set GLOBAL payload on the query (not unique per token)
   */
  void (*SetPayload)(struct RSQueryExpanderCtx *ctx, RSPayload payload);

} RSQueryExpanderCtx;

RSToken

RSToken 表示一个要扩展的单个查询 token，其定义如下：

/* A token in the query. The expanders receive query tokens and can expand the query with more query
 * tokens */
typedef struct {
  /* The token string - which may or may not be NULL terminated */
  const char *str;
  /* The token length */
  size_t len;
  
  /* 1 if the token is the result of query expansion */
  uint8_t expanded:1;

  /* Extension specific token flags that can be examined later by the scoring function */
  RSTokenFlags flags;
} RSToken;

评分函数 API

对于最终排名，评分函数会分析查询检索到的每个文档，不仅考虑触发文档检索的术语，还考虑其先验分数、长度等元数据。

由于评分函数对每个文档进行评估，可能执行数百万次，并且 Redis 是单线程的，因此它必须尽可能快地工作并进行大量优化。

评分函数应用于每个文档的每个潜在结果，其实现具有以下签名：

double MyScoringFunction(RSScoringFunctionCtx *ctx, RSIndexResult *res,
                                    RSDocumentMetadata *dmd, double minScore);

RSScoringFunctionCtx 是一个实现了一些辅助方法的上下文。

RSIndexResult 是结果信息，包含文档 ID、频率、术语和偏移量。

RSDocumentMetadata 是一个包含文档全局信息的对象，例如其推定分数。

minScore 是将产生与搜索相关的结果的最小分数。它可用于在中途或开始之前停止处理。

函数的返回值是一个 double 类型，表示结果的最终分数。返回 0 会使结果被计数，但如果有分数大于 0 的结果，它们将显示在其上方。要完全过滤掉结果并且不计入总数，评分器应返回特殊值 RS_SCORE_FILTEROUT，其内部设置为负无穷大或 -1/0。

RSScoringFunctionCtx

这是一个包含以下成员的对象：

  • void *privdata: 指向扩展在初始化时设置的对象的指针。
  • RSPayload payload*: 由查询扩展器或客户端设置的 Payload 对象。
  • int GetSlop(RSIndexResult *res)*: 一个回调方法，用于获取查询词之间的总最小距离。这可用于优先选择 slop 较小且词语更靠近的结果。

RSIndexResult

这是一个包含索引中当前结果信息的对象，它是导致当前文档被视为有效结果的所有术语的集合。有关详细信息，请参阅 redisearch.h。

RSDocumentMetadata

这是一个描述全局信息的对象，与当前查询无关，描述了由评分函数评估的文档。

示例查询扩展器

此示例查询扩展器将每个 token 扩展为术语 foo

#include <redisearch.h> //must be in the include path

void DummyExpander(RSQueryExpanderCtx *ctx, RSToken *token) {
    ctx->ExpandToken(ctx, strdup("foo"), strlen("foo"), 0x1337);  
}

示例评分函数

这是一个实际的评分函数，它计算文档的 TF-IDF，乘以文档分数，然后除以 slop

#include <redisearch.h> //must be in the include path

double TFIDFScorer(RSScoringFunctionCtx *ctx, RSIndexResult *h, RSDocumentMetadata *dmd,
                   double minScore) {
  // no need to evaluate documents with score 0 
  if (dmd->score == 0) return 0;

  // calculate sum(tf-idf) for each term in the result
  double tfidf = 0;
  for (int i = 0; i < h->numRecords; i++) {
    // take the term frequency and multiply by the term IDF, add that to the total
    tfidf += (float)h->records[i].freq * (h->records[i].term ? h->records[i].term->idf : 0);
  }
  // normalize by the maximal frequency of any term in the document   
  tfidf /=  (double)dmd->maxFreq;

  // multiply by the document score (between 0 and 1)
  tfidf *= dmd->score;

  // no need to factor the slop if tfidf is already below minimal score
  if (tfidf < minScore) {
    return 0;
  }

  // get the slop and divide the result by it, making sure we prefer results with closer terms
  tfidf /= (double)ctx->GetSlop(h);
  
  return tfidf;
}
评价本页
返回顶部 ↑