Typesense 中文文档

# Typesense API v28.0 参考文档

本文档详细介绍了 Typesense 中所有可用的 API 端点及其参数配置。

请使用左侧导航栏中的链接快速定位到您需要的部分。

如需了解如何安装和运行 Typesense，请参阅指南部分。


# 新特性

本版本包含重要的新功能、性能改进和错误修复。

# 新功能

  • 支持跨集合的搜索结果联合/合并（适用于包含相似字段类型的集合）(PR#2051 (opens new window))
  • 基于词典的词干提取：现在可以通过导入自定义词典来配置词干提取规则，词典中定义了单词到词根形式的映射 (PR#2062 (opens new window))
  • 支持通过 sort_by=_rand(seed) 参数对搜索结果进行随机排序 (PR#1918 (opens new window))
  • 混合搜索结果重排序功能：当命中结果仅来自关键词搜索或向量搜索时，可以通过增强其关键词/语义匹配分数来重新排序 (PR#1968 (opens new window))
  • 支持基于基准值（pivot value）对命中结果进行排序 (PR#2003 (opens new window))
  • 在 sort_by 中支持衰减函数（decay functions），包括高斯衰减、线性衰减和指数衰减 (PR#2036 (opens new window))
  • 现在支持字段级别的 token_separators（分词分隔符）和 symbols_to_index（需索引的符号）配置 (PR#2118 (opens new window))
  • 支持基于 bucket_size 参数对文本匹配分数进行分桶处理 (PR#2120 (opens new window))
  • 新增清空集合（truncate collection）功能 (PR#2127 (opens new window))
  • 支持地理多边形（geo polygons）的索引和搜索 (PR#2150 (opens new window))
  • 新增 validate_field_names 参数，用于禁用分面、过滤和分组操作中的字段名验证

# 功能增强

  • 支持为使用内积距离的向量查询添加 distance_threshold 参数
  • 允许更新远程模型的 api_key 参数 (PR#1944 (opens new window))
  • 新增 max_filter_by_candidates 搜索参数，用于控制模糊搜索时对 filter_by 值考虑的相似词数量（默认值为 4）
  • 优化关联查询的性能和稳定性
  • 新增 API 端点用于返回进行中的 schema 变更操作状态 (PR#2123 (opens new window))
  • 优化分面搜索性能

# 问题修复

  • 修复了带有 async_reference 属性的字段在重启后无法正确恢复的问题
  • 修复了嵌套引用字段的排序问题
  • 解决了对话 API 中的边界情况问题
  • 当按引用字段排序时，若引用不存在则分配默认排序分数
  • 修复了 vector_query 中的 distance_threshold 在排序时无效的问题
  • 添加验证确保 embedding 字段类型为 float[]
  • 修复向量查询格式验证的错误提示信息
  • 修复高并发图像 embedding 时的竞态条件问题
  • 修复 flat_search_cutoff 在混合搜索中无效的问题

# 废弃/行为变更

本版本没有废弃功能或行为变更。

# 升级指南

在将现有 Typesense 集群升级至 v28.0 之前，请仔细阅读上述行为变更说明，确保您的应用程序已做好升级准备。

我们建议先在开发/测试环境进行升级测试。

# Typesense Cloud 用户

如果您使用的是 Typesense Cloud：

  1. 访问 https://cloud.typesense.org/clusters (opens new window)
  2. 点击您的集群
  3. 在左侧面板点击"Cluster Configuration"，然后点击"Modify"
  4. 在下拉菜单中选择新的 Typesense Server 版本
  5. 安排升级时间

# 自托管部署

如果您是自行托管 Typesense，以下是升级方法：

# 单节点部署

  1. 出于安全考虑，先触发快照创建数据备份 (opens new window)
  2. 停止 Typesense 服务
  3. 通过 tar 包或 DEB/RPM 安装包替换二进制文件
  4. 重新启动 Typesense 服务

# 多节点集群部署

升级多节点集群时，我们将逐个节点进行操作，确保滚动升级期间集群保持健康状态。

注意： 升级过程中必须确保集群的 leader 节点仍在使用旧版 Typesense。因此我们将最后升级 leader 节点。您可以通过 /debug 端点响应中的 state 字段值来判断节点是 leader 还是 follower。

State 角色
1 LEADER
4 FOLLOWER
  1. 在 leader 节点上触发快照创建数据备份 (opens new window)
  2. 选择任一 follower 节点，停止 Typesense 服务并通过 tar 包或 DEB/RPM 安装包替换二进制文件
  3. 重新启动 Typesense 服务，等待节点以 follower 身份重新加入集群并完成数据同步（/health 应返回健康状态）
  4. 对其余 follower 节点重复步骤 2 和 3，暂时保持 leader 节点不受影响
  5. 当所有 follower 节点都升级到 v28.0 后，停止 leader 节点的 Typesense 服务
  6. 其他节点将选举出新的 leader 并继续工作
  7. 在旧的 leader 节点上替换二进制文件后重新启动 Typesense 服务
  8. 该节点将以 follower 身份重新加入集群，至此升级完成

# 降级指南

如果您希望将 Typesense 服务器降级到早期版本，可以安全地降级至 v27 版本。

TIP

本文档本身是开源的。如果您发现任何问题，点击页面底部的"编辑页面"按钮向我们提交 Pull Request。

服务器配置 →