typesense

Typesense 搜索服务器

补充说明

Typesense 是面向即时搜索的全文搜索引擎，支持拼写容错、分面过滤、地理位置和向量检索。默认端口 8108，使用 API Key 认证。

常用示例

启动服务：

docker run -d --name typesense \
  -p 8108:8108 \
  -v $(pwd)/typesense-data:/data \
  typesense/typesense:27.1 \
  --data-dir /data --api-key=*** --enable-cors

创建集合：

curl -X POST 'http://localhost:8108/collections' \
  -H 'X-TYPESENSE-API-KEY: ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"docs",
    "fields":[
      {"name":"title","type":"string"},
      {"name":"tag","type":"string","facet":true},
      {"name":"rank","type":"int32"},
      {"name":"embedding","type":"float[]","num_dim":1536,"optional":true}
    ],
    "default_sorting_field":"rank"
  }'

导入文档：

curl -X POST 'http://localhost:8108/collections/docs/documents/import?action=upsert' \
  -H 'X-TYPESENSE-API-KEY: ***' \
  -H 'Content-Type: text/plain' \
  --data-binary '{"id":"1","title":"磁盘满排查","tag":"linux","rank":10}'

搜索：

curl 'http://localhost:8108/collections/docs/search?q=磁盘&query_by=title&filter_by=tag:=linux' \
  -H 'X-TYPESENSE-API-KEY: ***'

创建快照：

curl -X POST 'http://localhost:8108/operations/snapshot?snapshot_path=/data/backup' \
  -H 'X-TYPESENSE-API-KEY: ***'

易错点与排错

• API Key 权限过大，前端直接暴露 admin key。
• schema 字段类型与导入数据不一致，文档被拒绝。
• num_dim 与向量维度不一致，向量检索失败。
• 过滤字段没有标记 facet 或类型不匹配，filter 无效。
• default_sorting_field 不存在，集合创建失败。
• 批量导入没有控制并发，内存和磁盘压力过高。
• 单节点没有快照和副本，故障后数据丢失。
• 中文搜索需要合适的 locale 和分词配置，否则召回差。

读完自测

合上页面，先回答，再展开对照。

1. 创建集合失败并提示 default_sorting_field，为什么？
2. 向量检索失败，先核对什么？
3. 前端直接使用 admin key 有什么风险？