highlight.io 基于 LLM Embeddings 的错误标签与错误分组实践

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文以 highlight.io 开源全栈可观测平台中的错误嵌入Error Embeddings模块为核心系统讲解如何利用 LLM 推理服务将错误文本转为向量、通过 pgvector 的 ivfflat 索引与欧几里得距离实现错误自动打标签如“认证错误”“数据库错误”和语义化错误分组。读完本文你将掌握该模块的数据模型、推理客户端实现、GraphQL 调用链与可复用的落地思路。一、背景为什么要给错误做“语义”传统错误监控平台通常依赖栈帧指纹stacktrace fingerprinting来做错误聚类但这只能捕获“结构完全相同”的错误。现实场景中两条错误可能栈与消息体不同语义却高度相似例如换了一种框架后抛出的同一种数据库连接失败传统的指纹方案无法把它们归为一组。highlight.io 在 backend/embeddings/README.md 中明确了两个目标错误标签Tagging自动把一条错误归类为“authentication error”“database error”等语义标签错误分组Grouping把栈与消息体不同、但语义相近的错误归并到同一组。其核心思路是把错误相关的文本事件名、错误类型、来源、栈、payload交给 LLM 推理端点得到高维浮点向量embedding再借助向量数据库比较相似度。二、整体架构文本 → 向量 → pgvector 相似度检索从 backend/embeddings/embeddings.go 可以看出整个链路分三步文本拼接由GetErrorObjectQuery把错误的Event、Type、Source、StackTrace优先取MappedStackTrace、Payload拼接成一个字符串向量化后端向推理端点发起请求拿到向量README 中描述为 1024 维对应thenlper/gte-large模型若走 OpenAI 客户端则使用AdaEmbeddingV2为 1536 维相似度检索向量存入 PostgreSQL 的 pgvector 列比较时使用 pgvector 的ivfflat 索引与欧几里得距离L2 distance。该模块的完整调用链是前端 GraphQL 请求 → resolverbackend/private-graph/graph/resolver.go→embeddings.MatchErrorTag→ 推理端点 pgvector 查询。三、数据模型向量列如何落库pgvector 的列类型通过 GORM tag 声明在 backend/model/model.go 中模型字段列类型说明ErrorObjectEmbeddingsCombinedEmbeddingvector(1536)由 OpenAI AdaEmbeddingV2 生成ErrorObjectEmbeddingsGteLargeEmbeddingvector(1024)由 thenlper/gte-large 生成ErrorTagEmbeddingvector(1024)标签自身的语义向量ErrorGroupEmbeddingsGteLargeEmbeddingvector(1024)错误分组用的向量对应关系见 backend/model/model.go#L1037-L1043 与 backend/model/model.go#L1077-L1082ErrorObjectEmbeddings每条错误对象ErrorObject一行分别记录两种模型产出的向量ErrorTag每个语义标签一行Title带唯一索引ErrorGroupEmbeddings以(ProjectID, ErrorGroupID)为唯一索引记录聚合到错误组后的向量。自定义类型Vectorbackend/model/model.go#L1752-L1763负责向量的序列化与反序列化存储格式类似 JSON 列表例如[-0.0123,0.456]并实现了driver.Valuer与sql.Scanner接口以适配数据库读写。四、两种推理客户端OpenAI 与 Hugging Facebackend/embeddings/embeddings.go 定义了统一的Client接口包含三个方法type Client interface { GetEmbeddings(ctx context.Context, errors []*model.ErrorObject) ([]*model.ErrorObjectEmbeddings, error) GetErrorTagEmbedding(ctx context.Context, title string, description string) (*model.ErrorTag, error) GetStringEmbedding(ctx context.Context, text string) ([]float32, error) }4.1 OpenAIClient批量向量化OpenAIClient封装了go-openai官方 SDK模型为openai.AdaEmbeddingV21536 维对应库中CombinedEmbedding列通过lo.Map对超长输入做截断保护当math.Ceil(len(item)/4.0) 8191即 token 数预估接近上限时截断到 32760 字节并记录 WARN 日志批量请求后按errorObject.ID聚合结果返回ErrorObjectEmbeddings请求会记录耗时、输入条数与 embedding 类型日志。4.2 HuggingfaceModelClient单条推理HuggingfaceModelClient直接通过 HTTP 调用自托管或远程的 Hugging Face 推理端点请求体结构为{inputs: text}携带Authorization: Bearer token响应解析为{Embeddings: []float32}状态码 ≥ 400 时返回错误每个错误的推理是串行执行的for idx, input : range combinedInputs默认构造器New()从环境变量读取配置backend/embeddings/embeddings.go#L262-L268。相关环境变量定义在 backend/env/environment.go#L79-L80HUGGINGFACE_API_TOKENxxx # 推理端点访问令牌 HUGGINGFACE_MODEL_URLhttps://... # 推理端点地址4.3 输入文本如何拼装GetErrorObjectQuerybackend/embeddings/embeddings.go#L178-L195按以下顺序拼接错误文本Event事件名/消息Type错误类型Source来源StackTrace——若存在MappedStackTrace则优先使用映射后的栈否则使用原始栈Payload附加负载可能为空各片段用空格连接作为推理端点的输入。这段拼接逻辑决定了“语义相似”的质量栈、事件、类型共同构成了一条错误最完整的语义描述。4.4 超时与性能约定InferenceTimeout 5 * time.Secondbackend/embeddings/embeddings.go#L30-L31源码注释注明推理 p95 耗时约 0.3 秒预留 5 秒上限是为了应对 API 偶发变慢。这是该模块在实际部署中对推理延迟的量化预期。五、错误标签从创建到语义匹配5.1 GraphQL 接口Schema 定义在 backend/private-graph/graph/schema.graphqls# 查询全部标签 error_tags: [ErrorTag] # 根据一段文本匹配最相近的标签 match_error_tag(query: String!): [MatchedErrorTag] # 创建标签同时生成其向量 createErrorTag(title: String!, description: String!): ErrorTag! # 全量刷新标签向量 updateErrorTags: Boolean!MatchedErrorTag包含id、title、description与score四个字段。5.2 创建与刷新CreateErrorTagbackend/private-graph/graph/resolver.go#L3783-L3797把title description交给GetErrorTagEmbedding生成向量随标签一起写入error_tags表UpdateErrorTagsbackend/private-graph/graph/resolver.go#L3799-L3821遍历全部已有标签重新调用推理端点生成向量并更新——在模型升级或想重新校准向量时使用。5.3 语义匹配-距离查询核心查询在MatchErrorTagbackend/embeddings/embeddings.go#L238-L260select error_tags.embedding - string_embedding as score, error_tags.id as id, error_tags.title as title, error_tags.description as description from error_tags order by score limit 5;关键点-是 pgvector 提供的L2欧几里得距离运算符与 README 描述的“Euclidian distance”完全对应查询先把用户输入字符串向量化再与error_tags中所有标签的向量逐一比较按距离升序取前 5 条参数通过sql.Named(string_embedding, model.Vector(stringEmbedding))绑定该查询同时被私有端管理员/开发者侧与公有端backend/public-graph/graph/resolver.go#L406复用例如在错误详情页实时给出“这条错误像哪种已知标签”的提示。匹配得到的最小score距离越小说明错误与标签语义越接近可据此阈值判断是否自动打上该标签。六、错误分组让“长得不一样”的错误归为一类README 明确了分组的判定标准两条错误即使 stacktrace 与 body 不同只要语义上差异不大就应归并到同一组。实现上依托同一套向量基础设施每条ErrorObject生成向量后存入ErrorObjectEmbeddings聚合后的错误组使用ErrorGroupEmbeddingsvector(1024)按(ProjectID, ErrorGroupID)唯一索引保存组级向量backend/model/model.go#L1118-L1124组间比较同样采用ivfflat索引加速的 L2 距离检索替代了传统“栈帧指纹必须完全一致”的硬性归并条件。对比传统指纹方案如 backend/model/model.go#L1132-L1151 中按CODE/META/JSON三种类型精确匹配的ErrorFingerprint嵌入方案的优势在于能捕捉“换了写法但本质相同”的错误缺点是引入了推理调用成本与向量存储成本需要结合准确率与延迟权衡。七、在 highlight.io 中的落地入口功能以error-tags页面形式对外提供README 指向 https://app.highlight.io/error-tags。从仓库代码可以还原完整的请求链路前端发起 GraphQL mutation/querybackend/private-graph/graph/schema.resolvers.go#L4496-L4504 与 backend/private-graph/graph/schema.resolvers.go#L8972-L8979 将请求转发给ResolverResolver调用r.EmbeddingsClient依赖注入的embeddings.Client完成向量化并通过 GORM 与 pgvector 完成存取backend/private-graph/graph/resolver.go。八、落地要点与限制基于仓库实现给出几条可落地的工程要点向量维度必须与模型一致列类型vector(N)的 N 必须匹配模型输出维度。仓库中 AdaEmbeddingV2 用 1536、gte-large 用 1024混用会导致写入失败或距离计算失真索引选择README 明确采用 pgvector 的ivfflat索引适合近似最近邻ANN检索场景数据量较大时应关注召回率与索引训练参数推理超时与重试参考InferenceTimeout 5s的约定推理端应提供足够的吞吐否则会阻塞错误写入链路输入长度控制OpenAI 客户端已内置 8191 token 上限的截断逻辑接入其他推理端点时需自行对齐其 token 限制环境变量接入本模块至少需要配置HUGGINGFACE_API_TOKEN与HUGGINGFACE_MODEL_URL两项。九、总结highlight.io 用一套“LLM 推理端点 pgvectorivfflat / L2 距离”的组合同时支撑了错误自动打标签与语义化错误分组两个特性。整体思路清晰、可复制把错误的结构化字段拼成自然语言向量化后交给向量数据库做最近邻检索。本文所涉实现均可在仓库中直接查看embeddings 客户端、数据模型、GraphQL 解析器 与 Schema 定义可作为自建错误语义分析能力的参考范本。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐DeepSeek Harness 结构化错误分类体系基于 HarnessError 的跨 Seam 错误路由与分类实践DeepSeek Harness 结构化错误分类体系基于 HarnessError 的跨 Seam 错误路由与分类实践 导读 本文深入解析 DeepSeek人工智能AI AgentAgent 框架DeepSeekPHPStan 错误 paramClosureThis.nonClosureparam-closure-this 标签误用于非 Closure 参数PHPStan 错误 paramClosureThis.nonClosure param closure this 标签误用于非 Closure 参数 导开发工具代码质量静态分析Dapr 错误码体系重构指南基于 gRPC 富错误模型的 Rich Error 实践Dapr 错误码体系重构指南基于 gRPC 富错误模型的 Rich Error 实践 导读 本指南面向在 Dapr 代码库中工作的开发者系统讲解 Dapr后端微服务云原生消息队列AI Agent上一篇开源项目管理利器GanttProject5个提升项目效率的核心功能深度解析下一篇如何3分钟为Word添加APA第7版格式学术写作的终极效率工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考