Weave Router ONNX 嵌入器工程化hugot、ORT 构建标签与 Qwen3-Embedding 导出全解【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/routerWeave Router是一个面向 Agent 系统的模型路由器它用本地 ONNX 嵌入模型为每个提示词打向量分在 50ms 内把请求路由到最合适的模型只需改一个端点地址就能省下 40–70% 的推理成本。本文带你拆解它的嵌入器工程化细节——如何用 hugot 在进程内跑 ONNX 推理、ORT构建标签为什么不可省略以及 Qwen3-Embedding-0.6B 的 ONNX 导出流水线是怎么做的。1️⃣ 嵌入器在 Weave Router 中扮演什么角色路由器的智能来自cluster scorer它把每个请求的提示词转成向量与预训练好的聚类中心做相似度比较再结合成本、速度等指标选出最优模型。向量由本地嵌入模型生成目前有两位选手 嵌入器 ID模型维度池化方式jina-v2-base-code-int8Jina Embeddings v2 (INT8)768均值池化模型输出 3D由 hugot 平均qwen3-embedding-0.6b-int8Qwen3-Embedding-0.6B (INT8)1024last-token 池化烘焙进 ONNX 图两者都通过 L2 归一化输出hugot 的WithNormalization。规格定义在 embedder.go运行时加载逻辑在 embedder_onnx.go。2️⃣ hugot ONNX Runtime为什么必须加-tags ORTGo 侧不直接调 Python而是用hugotgo.mod 中锁定github.com/knights-analytics/hugot v0.7.0onnxruntime_go在进程内跑 ONNX Runtime 推理单条嵌入只需几毫秒。工程上最关键的一条规则是生产构建必须带-tags ORT标签。缺少该标签时hugot.NewORTSession会在启动时报错router 会 fail-open 退化成启发式路由——服务看起来正常但聚类打分悄悄失效Makefile 的热重载目标make dev与 Dockerfile 的构建命令都显式带上-tags ORT注释里专门写了 Dont drop the tag。go build -tags ORT -o ./bin/server ./cmd/router这就是新手最容易踩的坑不加标签不会编译失败只会静默降级。3️⃣ Qwen3-Embedding 导出流水线一步不能少Qwen3 与 Jina 有个关键差异Qwen3 要求last-token pooling而 hugot 只会对 3D 输出做均值池化。项目给出的工程解法很巧妙——把池化烘焙进 ONNX 图让模型直接输出 2D 的[batch, 1024]Go 侧零特判代码训练/运行时一致性由构造保证。整条流水线由 scripts/export_qwen3_onnx.py 一键完成加载模型Qwen/Qwen3-Embedding-0.6Btransformers AutoModelfp32包一层池化LastTokenPooled按 attention mask 取每条序列最后一个真实 token无 L2 归一化交给运行时做导出 ONNXopset 18batch/sequence 动态轴输出名sentence_embeddingINT8 动态量化quantize_dynamic per-channel但故意排除down_proj(3072×1024) 和o_proj(2048×1024) 两个 MatMul——它们消费离群激活值量化后最坏情况相似度会跌破 0.98一致性自检用 8 条中/英/法/代码混合样本与 sentence-transformers 参考实现比对余弦相似度——fp32 ≥ 0.99、INT8 ≥ 0.98任一不达标直接失败退出产出 Go 测试夹具fixture.json拷到internal/router/cluster/testdata/fixture_qwen3.json让 Go 侧的 parity 测试套件复用同一批样本可选--upload推送到 Weave 的 HF 仓库并打印 commit SHA 供 Dockerfile 固定版本。产物目录布局与运行时严格对齐model.onnxINT8、model_fp32.onnx仅溯源、tokenizer.json。4️⃣ Dockerfile 多阶段构建嵌入器如何进镜像Dockerfile 的构建编排值得学习架构感知用TARGETARCH自动选择 ONNX Runtimev1.25.1amd64→x64 / arm64→aarch64和 libtokenizers 的对应 tarball避免在 Apple Silicon 上链到 x86_64 库模型拉取即版本固定Jina 权重从 HF 拉取并按 commit SHA 固定HF_MODEL_REVISION杜绝构建悄悄拿到新权重下载后校验model.onnx必须 1MB防止拿到的是授权跳转指针而非真权重按需装载Qwen3 的model.onnx约 1GB默认HF_QWEN_REPO为空即跳过下载——因为现有 bundle 都用 Jina运行时懒加载只有 bundle 真正声明该嵌入器时才会实例化它CGO 链参数CGO_CFLAGS-I/opt/onnxruntime/includeCGO_LDFLAGS-L… -lonnxruntime构建出的libonnxruntime.so单独拷入distroless/cc运行层必须 glibcmusl 起不来资产目录每个嵌入器一个子目录挂在/opt/router/assets/embedder-id/本地开发可用环境变量ROUTER_ONNX_ASSETS_DIR覆盖见 embedder_onnx.go。5️⃣ 嵌入空间契约训练与运行时必须逐位一致最容易发生的静默事故不是报错而是训练嵌入和运行时嵌入对不上导致错误路由。项目在 artifacts/README.md 中写死了契约bundle 的metadata.yaml声明embedder: {model, embed_dim, max_tokens}加载器交叉校验embed_dim与centroids.bin头拒绝让不同嵌入空间的 bundle 与嵌入器配对Qwen3 必须 1024 维Qwen3 bundle 要求last-token 池化 L2 归一化 无 instruction 前缀裸提示词、document 风格 尾部截断到 1024 字符提升 Qwen3 bundle 为latest之前必须跑延迟门禁目标生产 CPU 上 INT8 嵌入 p95 要留出余量地跑赢 1500ms 的EmbedTimeout——超时会直接 HTTP 503 而非降级。6️⃣ 常见问题速查 ❓Q为什么不用 Python 服务跑嵌入A每次路由都要算向量进程内 ONNX 推理没有网络往返配合 scorer 并发可稳定压进 50ms 预算。Q模型文件损坏会怎样A启动时主动检查文件存在且 1MBembedder_onnx.go 的minModelSizeBytes占位符/下载中断会被明确报错。Q本地开发要装什么ALinux 直接走 DockerfilemacOS 需在.env.local配置CGO_LDFLAGSlibtokenizers与ROUTER_ONNX_LIBRARY_DIRlibonnxruntime参考 Makefile 注释。7️⃣ 小结Weave Router 的嵌入器工程化给了三个可直接复用的经验烘焙进图的池化消灭模型特判、构建标签 启动检查防止静默降级、SHA 固定 一致性自检保证训练/推理/部署三位一体。想要深入了解聚类路由的训练侧设计可以继续读 artifacts/README.md 与 AGENTS.md。【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Weave Router ONNX 嵌入器工程化：hugot、ORT 构建标签与 Qwen3-Embedding 导出全解
Weave Router ONNX 嵌入器工程化hugot、ORT 构建标签与 Qwen3-Embedding 导出全解【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/routerWeave Router是一个面向 Agent 系统的模型路由器它用本地 ONNX 嵌入模型为每个提示词打向量分在 50ms 内把请求路由到最合适的模型只需改一个端点地址就能省下 40–70% 的推理成本。本文带你拆解它的嵌入器工程化细节——如何用 hugot 在进程内跑 ONNX 推理、ORT构建标签为什么不可省略以及 Qwen3-Embedding-0.6B 的 ONNX 导出流水线是怎么做的。1️⃣ 嵌入器在 Weave Router 中扮演什么角色路由器的智能来自cluster scorer它把每个请求的提示词转成向量与预训练好的聚类中心做相似度比较再结合成本、速度等指标选出最优模型。向量由本地嵌入模型生成目前有两位选手 嵌入器 ID模型维度池化方式jina-v2-base-code-int8Jina Embeddings v2 (INT8)768均值池化模型输出 3D由 hugot 平均qwen3-embedding-0.6b-int8Qwen3-Embedding-0.6B (INT8)1024last-token 池化烘焙进 ONNX 图两者都通过 L2 归一化输出hugot 的WithNormalization。规格定义在 embedder.go运行时加载逻辑在 embedder_onnx.go。2️⃣ hugot ONNX Runtime为什么必须加-tags ORTGo 侧不直接调 Python而是用hugotgo.mod 中锁定github.com/knights-analytics/hugot v0.7.0onnxruntime_go在进程内跑 ONNX Runtime 推理单条嵌入只需几毫秒。工程上最关键的一条规则是生产构建必须带-tags ORT标签。缺少该标签时hugot.NewORTSession会在启动时报错router 会 fail-open 退化成启发式路由——服务看起来正常但聚类打分悄悄失效Makefile 的热重载目标make dev与 Dockerfile 的构建命令都显式带上-tags ORT注释里专门写了 Dont drop the tag。go build -tags ORT -o ./bin/server ./cmd/router这就是新手最容易踩的坑不加标签不会编译失败只会静默降级。3️⃣ Qwen3-Embedding 导出流水线一步不能少Qwen3 与 Jina 有个关键差异Qwen3 要求last-token pooling而 hugot 只会对 3D 输出做均值池化。项目给出的工程解法很巧妙——把池化烘焙进 ONNX 图让模型直接输出 2D 的[batch, 1024]Go 侧零特判代码训练/运行时一致性由构造保证。整条流水线由 scripts/export_qwen3_onnx.py 一键完成加载模型Qwen/Qwen3-Embedding-0.6Btransformers AutoModelfp32包一层池化LastTokenPooled按 attention mask 取每条序列最后一个真实 token无 L2 归一化交给运行时做导出 ONNXopset 18batch/sequence 动态轴输出名sentence_embeddingINT8 动态量化quantize_dynamic per-channel但故意排除down_proj(3072×1024) 和o_proj(2048×1024) 两个 MatMul——它们消费离群激活值量化后最坏情况相似度会跌破 0.98一致性自检用 8 条中/英/法/代码混合样本与 sentence-transformers 参考实现比对余弦相似度——fp32 ≥ 0.99、INT8 ≥ 0.98任一不达标直接失败退出产出 Go 测试夹具fixture.json拷到internal/router/cluster/testdata/fixture_qwen3.json让 Go 侧的 parity 测试套件复用同一批样本可选--upload推送到 Weave 的 HF 仓库并打印 commit SHA 供 Dockerfile 固定版本。产物目录布局与运行时严格对齐model.onnxINT8、model_fp32.onnx仅溯源、tokenizer.json。4️⃣ Dockerfile 多阶段构建嵌入器如何进镜像Dockerfile 的构建编排值得学习架构感知用TARGETARCH自动选择 ONNX Runtimev1.25.1amd64→x64 / arm64→aarch64和 libtokenizers 的对应 tarball避免在 Apple Silicon 上链到 x86_64 库模型拉取即版本固定Jina 权重从 HF 拉取并按 commit SHA 固定HF_MODEL_REVISION杜绝构建悄悄拿到新权重下载后校验model.onnx必须 1MB防止拿到的是授权跳转指针而非真权重按需装载Qwen3 的model.onnx约 1GB默认HF_QWEN_REPO为空即跳过下载——因为现有 bundle 都用 Jina运行时懒加载只有 bundle 真正声明该嵌入器时才会实例化它CGO 链参数CGO_CFLAGS-I/opt/onnxruntime/includeCGO_LDFLAGS-L… -lonnxruntime构建出的libonnxruntime.so单独拷入distroless/cc运行层必须 glibcmusl 起不来资产目录每个嵌入器一个子目录挂在/opt/router/assets/embedder-id/本地开发可用环境变量ROUTER_ONNX_ASSETS_DIR覆盖见 embedder_onnx.go。5️⃣ 嵌入空间契约训练与运行时必须逐位一致最容易发生的静默事故不是报错而是训练嵌入和运行时嵌入对不上导致错误路由。项目在 artifacts/README.md 中写死了契约bundle 的metadata.yaml声明embedder: {model, embed_dim, max_tokens}加载器交叉校验embed_dim与centroids.bin头拒绝让不同嵌入空间的 bundle 与嵌入器配对Qwen3 必须 1024 维Qwen3 bundle 要求last-token 池化 L2 归一化 无 instruction 前缀裸提示词、document 风格 尾部截断到 1024 字符提升 Qwen3 bundle 为latest之前必须跑延迟门禁目标生产 CPU 上 INT8 嵌入 p95 要留出余量地跑赢 1500ms 的EmbedTimeout——超时会直接 HTTP 503 而非降级。6️⃣ 常见问题速查 ❓Q为什么不用 Python 服务跑嵌入A每次路由都要算向量进程内 ONNX 推理没有网络往返配合 scorer 并发可稳定压进 50ms 预算。Q模型文件损坏会怎样A启动时主动检查文件存在且 1MBembedder_onnx.go 的minModelSizeBytes占位符/下载中断会被明确报错。Q本地开发要装什么ALinux 直接走 DockerfilemacOS 需在.env.local配置CGO_LDFLAGSlibtokenizers与ROUTER_ONNX_LIBRARY_DIRlibonnxruntime参考 Makefile 注释。7️⃣ 小结Weave Router 的嵌入器工程化给了三个可直接复用的经验烘焙进图的池化消灭模型特判、构建标签 启动检查防止静默降级、SHA 固定 一致性自检保证训练/推理/部署三位一体。想要深入了解聚类路由的训练侧设计可以继续读 artifacts/README.md 与 AGENTS.md。【免费下载链接】routerModel router for agentic systems. Routes every prompt to the right model in 50ms. Cut costs 40-70% with just an endpoint change.项目地址: https://gitcode.com/GitHub_Trending/router101/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考