文档 / 全文搜索

全文搜索

全文搜索让你能够在 traces 和 observations 的输入、输出和元数据中查找特定关键词或短语的所有出现。这在调试复杂应用时尤其有用——你记得某段内容,但不记得它属于哪个 trace。

在 UI 中搜索

使用 traces 和 observations 表格上方的搜索栏,跨 input 和 output 内容搜索。匹配的 traces 和 observations 会被返回,让你能快速定位你要找的运行,并将搜索与现有过滤器和时间范围选择器结合使用。

在 v4 的 Observations 和 Traces 表格上,全文搜索也可在 Filter Search Bar 中内联使用,与 level:ERROR 和 latency:>2 等结构化过滤器并列。

搜索使用 ClickHouse 全文搜索。文本索引让 Langfuse 能够在读取完整 observation 负载之前跳过不可能匹配查询的数据,即使对于拥有高流量 traces 的大型项目,搜索也能保持快速。你可以在 ClickHouse GA 公告中阅读更多。

由于这些索引基于 token,查询匹配的是整个词而非其中的子串——error 匹配 error 但不匹配 errors——而多词查询作为连续短语匹配。

Observations API v2 支持 matches 运算符,用于对 input、output 和字符串 metadata 过滤器进行基于 token 的全文搜索。

在 /api/public/v2/observations 上构建过滤器时,当你知道确切值时优先使用 =,当你想要基于 token 的搜索时使用 matches:

matches 对 input 和 output 不区分大小写,因此 refund failed 可以匹配 Refund Failed。
对于元数据过滤器,matches 区分大小写,并应用于所选键的字符串元数据值。
子串运算符,如 contains、starts with 和 ends with,在 input 和 output 过滤器上会以 400 被拒绝,因为它们需要缓慢的全内容扫描。请改用 matches 对这些字段进行 token 搜索。

observation 输出的 matches 过滤器示例:

json

[
  {
    "type": "string",
    "column": "output",
    "operator": "matches",
    "value": "refund failed"
  }
]

精确元数据过滤器示例:

json

[
  {
    "type": "stringObject",
    "column": "metadata",
    "key": "environment",
    "operator": "=",
    "value": "production"
  }
]

将该 JSON 数组作为 URL 编码的 filter 查询参数传递给 GET /api/public/v2/observations。完整的过滤器 schema 参见 Observations API v2 文档和 API 参考。