AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载本篇文章以 AxonHub 开源 AI Gateway 中internal/contexts上下文管理系统为骨架深入讲解 Thread线程/会话与 Trace追踪实体如何在单个请求的完整生命周期中被存储、传递、检索与落库。读者将掌握WithThread/GetThread、WithTrace/GetTrace等上下文 API 的使用方式、中间件装配顺序与配置项并能直接在自己的 Handler 与客户端调用中复现这套端到端追踪方案。为什么需要把 Thread 与 Trace 放进 Context在 AxonHub 这类 AI Gateway 中一次用户请求会经过鉴权、项目解析、渠道选择、LLM 转发、日志记录等多个环节。为了让「同一次会话」和「同一条追踪」的信息贯穿整个处理链路需要一种不侵入函数签名的传递机制Go 标准库的context.Context正是最合适的载体。internal/contexts包在既有上下文体系API Key、User、Project ID、Request ID 等基础上新增了两个业务实体*ent.Thread与*ent.Trace使其可以随请求在整个生命周期内被存取。对应的实现位于 internal/contexts/thread.go 与 internal/contexts/trace.go。核心设计可以概括为三层层级位置职责上下文存储层internal/contexts/提供WithThread/GetThread、WithTrace/GetTrace纯函数式存取业务逻辑层internal/server/biz/thread.go、internal/server/biz/trace.goGetOrCreate幂等读写数据库中的 Thread / Trace 实体中间件层internal/server/middleware/thread.go、internal/server/middleware/trace.go从请求头提取 ID自动完成实体创建并注入上下文上下文存储层With / Get 的原子语义Thread 的存取thread.go只做了两件事把实体放入容器、从容器取出实体。// WithThread stores the thread entity in the context. func WithThread(ctx context.Context, thread *ent.Thread) context.Context { container : getContainer(ctx) container.Thread thread return withContainer(ctx, container) } // GetThread retrieves the thread entity from the context. func GetThread(ctx context.Context) (*ent.Thread, bool) { container : getContainer(ctx) return container.Thread, container.Thread ! nil }Trace 的存取trace.go遵循完全相同的模式返回值中的bool用于区分「上下文中存在实体」与「不存在实体」两种状态避免调用方把 nil 误当作有效数据func WithTrace(ctx context.Context, trace *ent.Trace) context.Context { container : getContainer(ctx) container.Trace trace return withContainer(ctx, container) } func GetTrace(ctx context.Context) (*ent.Trace, bool) { container : getContainer(ctx) return container.Trace, container.Trace ! nil }底层容器机制这两个文件背后的容器定义在 internal/contexts/container.go。contextContainer是一个可变的请求级值容器同时容纳ProjectID、TraceID、RequestID、APIKey、User、Thread、Trace、Errors等字段并通过sync.RWMutex保护并发读写type contextContainer struct { ProjectID *int TraceID *string RequestID *string OperationName *string APIKey *ent.APIKey User *ent.User Source *request.Source Thread *ent.Thread Trace *ent.Trace Errors []error mu sync.RWMutex ChannelAPIKey *string }getContainer在上下文没有容器时惰性新建withContainer仅在容器尚未写入时通过context.WithValue挂载避免覆盖已有容器。这种「先取容器 → 改字段 → 回写」的模式让多个With*调用可以叠加在同一份容器上且彼此之间互不覆盖对应测试TestContextContainerMultipleValues、TestContextContainerOverwrite与TestContextContainerIsolation覆盖了叠加、覆盖与隔离三种场景见 internal/contexts/context_test.go。补充该包还提供了EnsureContainer、WithAPIKey、WithUser、WithProjectID、AddError/GetErrors等通用工具与 Thread/Trace 共享同一容器意味着 Handler 中一次GetThread可以同时拿到项目 ID、用户等全套请求上下文。业务逻辑层GetOrCreate 的幂等落库ThreadServiceinternal/server/biz/thread.go 中的ThreadService提供两个核心方法GetOrCreateThread(ctx, projectID, threadID)先按thread_id project_id查询命中直接返回未命中则创建若创建时触发唯一约束冲突并发竞态再回退为查询从而保证幂等。GetThreadByID(ctx, threadID, projectID)按thread_id project_id精确查询单个线程。从源码实现看查询与写入都通过 ent 客户端完成且创建成功后写入 debug 日志log.Debug(ctx, created new thread, ...)便于追踪新实体的产生时机。TraceServiceinternal/server/biz/trace.go 中的TraceService核心方法GetOrCreateTrace(ctx, projectID, traceID, threadID)查询逻辑与 Thread 一致但创建时通过SetNillableThreadID(threadID)支持可选地关联到某个 Thread这是 Thread–Trace 关系落库的关键一步。GetTraceByID(ctx, traceID, projectID)按trace_id project_id查询单个追踪。两个 Service 在实现上的共性值得注意幂等性由「查询 → 创建 → 约束冲突回退查询」三阶段保证。单测TestThreadService_GetOrCreateThreadinternal/server/biz/thread_test.go验证了同一 ID 两次调用返回同一实体TestTraceService_GetOrCreateTrace与TestTraceService_GetOrCreateTrace_WithThreadinternal/server/biz/trace_test.go则额外验证了传入 threadID 指针时 trace 会正确落库ThreadID。全局唯一性由数据库唯一索引兜底。Thread 与 Trace 的 Schema 中thread_id/trace_id字段均声明Unique()见 internal/ent/schema/thread.go 与 internal/ent/schema/trace.go。这意味着无论请求来自哪个项目同一个 ID 只能对应一条实体记录。项目隔离GetOrCreate的查询条件永远同时携带project_id不同项目即使使用相同的 thread_id 也不会互相串扰测试TestThreadService_GetOrCreateThread_DifferentProjects、TestTraceService_GetOrCreateTrace_DifferentProjects验证了这一点。此外TraceService 还承担了更重的追踪展示职责GetRootSegment会把一条 Trace 下的全部请求在内存中构建为 Segment 树通过 tool_call_id 关联、span 前缀匹配、时间最近回退三级策略寻找父节点并为跨 Trace 去重提供支持。源码注释明确给出了性能边界假设——单个 Trace 通常包含合理数量的请求10-50 个典型、上限 100 个可接受、超过 1000 个应拆分单请求体约 1-5MB因此并发加载限制为MaxConcurrentBodyLoads 10。这些属于从源码结构可推断的实现取舍可作为设计同类追踪系统时的参考。中间件层从请求头到实体的自动化流水线装配顺序order mattersREADME 与 internal/server/routes.go 中的真实装配代码都强调了一个关键点中间件顺序不能乱。// Initialize services threadService : biz.NewThreadService() traceService : biz.NewTraceService() // Add middleware to router (order matters) router.Use(middleware.WithProjectID()) // Must come first router.Use(middleware.WithThreadID(threadService)) router.Use(middleware.WithTraceID(traceService))在 AxonHub 实际的 API 路由中顺序为WithProjectID→WithSource→WithResponseHeaders→WithThread→WithTrace见 internal/server/routes.goGemini 路由同样保持WithThread在WithTrace之前internal/server/routes.go。这个顺序的原因如下WithProjectID必须最先执行因为后续两个中间件都需要从上下文中读取 Project ID 才能创建实体WithThread必须先于WithTrace因为 Trace 中间件在创建 Trace 时会检查上下文中是否已有 Thread有则自动把thread.ID关联到新 Trace 上。WithThreadID读取 X-Thread-ID / AH-Thread-Idinternal/server/middleware/thread.go 中WithThread的实现要点默认读取AH-Thread-Id请求头可通过tracing.Config.ThreadHeader覆盖见 internal/tracing/tracing.go请求头为空直接放行c.Next()从上下文读取 Project ID读不到则放行——对应 README 的「Project Requirement」通过authz.WithSystemBypass绕过权限策略让没有write_requestsscope 的令牌也能触发线程追踪调用GetOrCreateThread出错时仅记录 warning 日志不阻断请求——对应 README 的「Non-blocking」成功后用contexts.WithThread注入并替换c.Request的上下文。中间件集成测试TestWithThreadID_Success、TestWithThreadID_NoHeader、TestWithThreadID_NoProjectID、TestWithThreadID_Idempotentinternal/server/middleware/thread_test.go分别覆盖了成功创建、无头放行、缺 Project ID 跳过、重复请求返回同一实体四种行为。WithTraceID多来源提取 Trace IDinternal/server/middleware/trace.go 中的WithTrace实现比 Thread 复杂得多其 Trace ID 提取遵循多级回退主 Trace 头默认AH-Trace-Idconfig.ExtraTraceHeaders中配置的附加头如Sentry-TraceOpenCodeTraceEnabled时从 OpenCode session 头提取ClaudeCodeTraceEnabled时从/anthropic/v1/messages请求体的metadata.user_id提取仅 POST 且路径匹配CodexTraceEnabled时从 Codex 的Session_id头提取ExtraTraceBodyFields配置的 JSON body 字段提取基于 gjson 的trace_id、metadata.trace_id等路径。提取到 Trace ID 后中间件还会将最终解析出的 trace ID 同步写回请求上下文tracing.WithTraceID并写入ResponseTraceHeaders配置的响应头供客户端与上游网关联动对/embeddings、:embedContent等非消息型端点isNonMessageEndpoint只保留 trace ID 供日志关联但不创建持久化的 Trace 实体从上下文读取 Thread若存在并把thread.ID传给GetOrCreateTrace实现自动关联同样使用authz.WithSystemBypass与「出错仅记日志、继续请求」的非阻塞策略成功后把 Trace 注入上下文并用shared.WithSessionID把 trace ID 设为 session ID 供 Provider 侧缓存使用。对应的单元测试覆盖了各提取来源、优先级、body 字段嵌套与优先级TestWithTrace_ExtraTraceBodyFields、TestWithTrace_ExtraTraceBodyFields_Nested、TestWithTrace_ExtraTraceBodyFields_Priority等见 internal/server/middleware/trace_test.go以及 Thread 关联场景TestWithTraceID_WithThread同文件 internal/server/middleware/trace_test.go该测试断言新建 Trace 的ThreadID与预置 Thread 的 ID 相等。在 Handler 中使用上下文实体READMe 给出的 Handler 侧用法可以直接落地func MyHandler(c *gin.Context) { // Get thread from context if thread, ok : contexts.GetThread(c.Request.Context()); ok { // Use thread fmt.Printf(Thread ID: %s\n, thread.ThreadID) } // Get trace from context if trace, ok : contexts.GetTrace(c.Request.Context()); ok { // Use trace fmt.Printf(Trace ID: %s\n, trace.TraceID) if trace.ThreadID ! 0 { fmt.Printf(Linked to Thread: %d\n, trace.ThreadID) } } }这里需要注意两点必须使用c.Request.Context()而非c本身因为中间件注入实体时替换的是 Request 的 contextGetThread/GetTrace返回的bool用于判断实体是否真实存在在日志、鉴权或计费逻辑中应先做存在性判断再使用字段。客户端接入通过请求头传递会话与追踪 IDREADME 给出的 curl 示例注README 中头名写作X-Thread-ID/X-Trace-IDAxonHub 当前实际默认头名为AH-Thread-Id/AH-Trace-Id可通过配置覆盖curl -H X-Project-ID: proj_123 \ -H X-Thread-ID: thread-abc-123 \ -H X-Trace-ID: trace-xyz-456 \ https://api.example.com/endpoint对应到 AxonHub 的实际默认头名一次带追踪的 OpenAI 兼容调用形如curl https://your-axonhub-instance/v1/chat/completions \ -H Authorization: Bearer ${AXONHUB_API_KEY} \ -H Content-Type: application/json \ -H AH-Trace-Id: at-demo-123 \ -H AH-Thread-Id: thread-abc \ -d { model: gpt-4o, messages: [ { role: user, content: Diagnose latency in my pipeline } ] }使用要点希望多次请求落在同一条追踪时务必显式提供AH-Trace-Id缺失时各请求会被分别记录虽然中间件层会为日志关联生成 ID但不会因此创建持久化 Trace参见 internal/server/middleware/trace.go 中「Only explicitly configured trace sources should create a trace record」的注释任意 OpenAI 兼容 SDK 均可直接使用只需在请求级别附加这两个头即可。仓库中可运行样例见integration_test/anthropic/trace_multiple_requests/trace_test.go与integration_test/gemini/trace_multiple_requests/trace_test.go。配置项全解与 Thread/Trace 追踪相关的配置集中在server.trace段见 config.example.yml 与 internal/tracing/tracing.go配置项默认值说明thread_headerAH-Thread-IdThread ID 请求头名留空则用默认名trace_headerAH-Trace-IdTrace ID 请求头名留空则用默认名extra_trace_headers[]附加 Trace 头主 Trace 头缺失时依次尝试如Sentry-Trace可用于聚合 Claude Code 等产物response_trace_headers[]响应开始前回写最终 Trace ID 的头列表为空不回写可为上游网关配置多个兼容头extra_trace_body_fields[]请求体中用于提取 Trace ID 的 JSON 路径如trace_id、metadata.trace_idclaude_code_trace_enabledtrue从 Claude Code 请求metadata.user_id自动提取 Trace IDcodex_trace_enabledtrue从 CodexSession_id头自动提取 Trace IDopencode_trace_enabledtrue从 OpenCode session 头自动提取 Trace ID典型完整配置示例对齐 docs/zh/guides/tracing.md# config.yml server: trace: thread_header: AH-Thread-Id trace_header: AH-Trace-Id extra_trace_headers: - Sentry-Trace response_trace_headers: - AH-Trace-Id - X-Oneapi-Request-Id补充要点extra_trace_headers用于复用客户端已有的埋点请求头response_trace_headers与入站解析配置相互独立且可配置多个头若浏览器客户端需要读取响应中的这些头还应把对应名称加入server.cors.exposed_headers所有配置项均提供同名环境变量如AXONHUB_SERVER_TRACE_THREAD_HEADER、AXONHUB_SERVER_TRACE_TRACE_HEADER默认值在 conf/conf.go 中设置Claude Code / Codex / OpenCode 自动提取与显式 Trace 头兼容请求已携带 Trace 头时系统优先使用显式值。数据模型Schema 层面的约束从 ent Schema 可以确认 README「Important Notes」中各项声明的底层依据全局唯一thread_id、trace_id字段均Unique()对应唯一索引见 internal/ent/schema/thread.gothreads_by_thread_id与 internal/ent/schema/trace.gotraces_by_trace_id项目关联两者都有不可变的project_id字段并建有project_id索引与(project_id, status)复合索引Thread–Trace 关联Trace 的thread_id字段为Optional()Immutable()且建立traces_by_thread_id索引Schema 边定义中 Thread 拥有traces边、Trace 拥有thread边状态机两者都有status枚举active/archived/retained默认active。业务层对应提供Archive/Unarchive/Retain/Unretain方法——Thread 的归档/保留会以事务方式级联到其下所有 Trace见 internal/server/biz/thread.go而 Trace 的状态切换只作用于自身。关键行为总结Important Notes 对照全局唯一thread_id与trace_id在全部项目范围内全局唯一由数据库唯一索引强制保证。Project 前提两个中间件都要求上下文中已有 Project ID缺失时跳过实体创建、直接放行。非阻塞实体创建失败仅记 warning 日志请求继续执行不因追踪失败而中断业务。Thread–Trace 关系Trace 可选关联 Thread创建 Trace 时若上下文中已有 Thread会自动完成关联GetOrCreateTrace通过SetNillableThreadID落库。幂等GetOrCreate系列方法对同一 ID 多次调用返回同一实体重复请求不会产生重复记录。测试与验证README 中列出的测试命令可直接在仓库根目录运行go test ./internal/contexts/ go test ./internal/server/biz/thread_test.go ./internal/server/biz/thread.go go test ./internal/server/biz/trace_test.go ./internal/server/biz/trace.go go test ./internal/server/middleware/thread_test.go ./internal/server/middleware/thread.go go test ./internal/server/middleware/trace_test.go ./internal/server/middleware/trace.go测试体系覆盖五类场景上下文存取含叠加、覆盖、隔离、业务逻辑数据库操作含幂等与跨项目隔离、中间件集成含多来源提取与优先级、幂等性、错误处理如 ent client 缺失时返回错误。另外TestWithTrace_SkipsPersistedTraceForEmbeddingEndpointinternal/server/middleware/trace_test.go验证了 embeddings 端点只保留 trace ID 而不落库的边界行为。常见问题排查未生成追踪确认请求已通过认证且 Project ID 正确解析API Key 必须隶属于某个项目否则中间件会因上下文缺少 Project ID 而跳过实体创建。缺少线程关联在请求中提供AH-Thread-Id或先通过 API 创建 Thread 后再发起 Trace 请求。Trace ID 异常检查上游代理或网关是否覆盖/剥离了AH-Trace-Id、AH-Thread-Id等请求头。单 Trace 请求过多参考源码中GetRootSegment的设计假设单条 Trace 建议控制在 100 个请求以内超过 1000 个会带来显著的内存与页面加载开销复杂 agent 工作流应拆分为多个 Trace 并用同一 Thread 关联。赞分享AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载相关推荐无需算法基础4步做出文档问答应用LLM Universe 动手学大模型应用开发无需算法基础4步做出文档问答应用LLM Universe 动手学大模型应用开发 LLM Universe动手学大模型应用开发是 Datawhale 出品AI 应用API网关LLM 网关后端前端终极命名实体识别利器TensorFlow LSTMCRF实战指南 - sequence_tagging项目深度解析终极命名实体识别利器TensorFlow LSTMCRF实战指南 sequence_tagging项目深度解析 sequence_tagging是一个基于T终极指南Go-Redis连接池与请求生命周期控制全解析终极指南Go Redis连接池与请求生命周期控制全解析 Go Redis是Go语言生态中最流行的Redis客户端库之一提供了高效的连接管理和丰富的功能特性。后端数据库客户端缓存上一篇Linux 内核 CPU 热插拔CPU Hotplug机制完全解析从 sysfs 实操到状态机内核 API下一篇Wazuh DBSync 冒烟测试实战使用 dbsync_test_tool 验证 Insert / Update / Delete / Select 全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考