后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载Provider Mocker 是 Semantic Router 项目中一个无需下载模型、无需 GPU、无需上游推理服务的确定性 Provider 服务模拟器用于 Router 契约测试与本地开发。本文将以 deploy/kubernetes/provider-mocker/README.md 为主线完整讲解其在 Kuberneteskind集群中的构建、加载、部署与端口转发流程并结合 tools/test/services/provider-mocker 的源码深入剖析其原生协议端点、六大场景、协议标记输入与环境变量配置帮助你把它接入 Router 的 E2E 测试和本地联调链路。一、Provider Mocker 是什么一个可编程的“假 Provider”在语义路由器Semantic Router的开发和测试过程中真实的大模型推理服务往往难以获取需要下载权重、申请 GPU、等待模型加载且输出不可控无法用来验证 Router 的分发、回退、熔断等契约行为。Provider Mocker 就是为了解决这一问题而设计的确定性 Provider 服务。它的核心特征是原生提供Chat Completions、Responses、Anthropic Messages 和图像生成image-generation四种协议不需要下载任何模型即可运行输出完全确定性deterministic适合作为 Router 契约测试的稳定基准其原生 wire handler独立于生产 Router 的编解码codec实现因此可以交叉验证协议兼容性运行在纯 PythonFastAPI进程中无模型权重、无 GPU、无上游推理服务器。从代码结构看模拟器是一个独立的 Python 包位于 tools/test/services/provider-mocker/provider_mocker由app.pyFastAPI 应用、chat.py/responses.py/messages.py/images.py各原生协议端点、scenarios.py场景分发和settings.py环境变量配置等模块组成并配套 16 个契约测试文件例如 test_native_protocols.py、test_scenarios.py 与 test_shadow_control.py。注意区分Provider Mocker 只做协议层面的确定性模拟。如果确实需要小模型的真实推理来验证 Router 行为仓库在 tools/test/services/tiny-model 提供了可选的 Qwen3-0.6B runner二者是可选的互补关系Provider Mocker 镜像内不捆绑任何推理引擎。二、在 Kubernetes 集群中部署 Provider Mocker仓库在 deploy/kubernetes/provider-mocker 下提供了开箱即用的 Kustomize 清单共四个文件README.md、deployment.yaml、service.yaml 和 kustomization.yaml。2.1 标准部署流程kind 本地集群原文档给出的完整操作序列如下make docker-build-provider-mocker kind load docker-image semantic-router-ci/provider-mocker:e2e-test kubectl apply -k deploy/kubernetes/provider-mocker kubectl rollout status deployment/provider-mocker kubectl port-forward service/provider-mocker 8000:8000各步骤的作用make docker-build-provider-mocker构建模拟器镜像默认标签为semantic-router-ci/provider-mocker:e2e-test若已显式指定PROVIDER_MOCKER_PREBUILT/E2E_PREBUILT_PROVIDER_MOCKER_IMAGE则会复用既有镜像见 tools/make/docker.mkkind load docker-image将镜像导入 kind 集群节点因为清单使用本地镜像kubectl apply -k用 Kustomize 方式应用deployment.yaml与service.yamlkubectl rollout status等待 Deployment 就绪kubectl port-forward把集群内的 8000 端口映射到本机 8000供 Router / 测试客户端访问。2.2 清单内容详解Deploymentdeployment.yaml副本数固定为 1容器端口 8000命名为http并使用就绪探针readinessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 1 periodSeconds: 2探针每 2 秒请求一次/health初始延迟 1 秒。这要求模拟器启动后立即在/health上就绪——app.py中确实实现了该健康检查端点任何使用该清单的集群都必须保持此探针路径不变。Serviceservice.yaml通过 selectorapp: provider-mocker关联 Pod端口 8000 直接映射到容器的 8000。Kustomizationkustomization.yaml声明namespace: default并聚合两个资源文件因此可以用一条kubectl apply -k命令完成部署。2.3 远程集群的镜像替换要求原文档明确指出清单默认使用本地镜像imagePullPolicy: Never只适合 kind 这类本地集群。在远程集群上必须将image改为已发布的provider-mockersha256:...摘要digest形式将imagePullPolicy改为IfNotPresent。不修改这两项远程节点将无法拉取semantic-router-ci/provider-mocker:e2e-test这个本地镜像。2.4 Makefile 封装的便捷命令仓库在 tools/make/kube.mk 中封装了一组与上述流程等价的命令适合在 CI 或日常开发中使用Make 目标行为kube-load-provider-mocker-image构建并kind load镜像到指定集群KIND_CLUSTER_NAMEkube-deploy-provider-mocker加载镜像 →kubectl apply -k→ 设置镜像 →rollout status超时 120skube-undeploy-provider-mocker按-k清单删除--ignore-not-foundtruekube-status-provider-mocker展示带标签appprovider-mocker的 Deployment/Pod/Servicekube-logs-provider-mocker跟随 Deployment 日志kube-port-forward-provider-mocker将service/provider-mocker的 8000 端口转发到本机PROVIDER_MOCKER_PORT默认 8000相关变量包括PROVIDER_MOCKER_NAMESPACE ? default与PROVIDER_MOCKER_BASE_PATH ? deploy/kubernetes/provider-mocker可通过 Makefile 参数覆盖。三、模拟器的原生协议端点模拟器通过 FastAPI 暴露一组与真实 Provider 完全对齐的 HTTP 端点完整列表见 tools/test/services/provider-mocker/README.md 中的契约表端点契约POST /v1/chat/completionsChat Completions支持 buffered 与 SSE 流式POST /v1/responsesResponses支持 buffered 与 SSE含图像生成事件POST /v1/messagesAnthropic Messages支持 buffered 与 SSE、工具调用、stop sequences 与缓存计数器POST /v1/images/generationsBuffered 图像返回确定性的合法 1×1 PNGGET /health就绪检查GET /v1/models返回已配置的模型元数据POST /classify远程分类器与响应护栏response guard测试夹具GET /debug/last-request返回测试会话中最后一次原生请求其中图像端点接受response_format: b64_json与n1 到 4。图像流式、URL 结果、图像编辑及不支持的字段会显式失败而不是静默忽略固定 PNG 用于验证响应分帧与图像解码逻辑不代表图像质量。从源码看这些端点位于 responses.py、messages.py 与 images.py。请求观察observation机制会保留原始 JSON、请求路径、Authorization头的 SHA-256 摘要而非明文凭证并且只保留x-vsr-test-session-id与x-vsr-e2e-*头会话通过该头或查询参数区分否则共享__global__。观察与缓存状态受上限约束且仅存在于单一 service worker 内部。四、场景Scenario用环境变量选择确定性行为4.1 六大内置场景模拟器的核心灵活性来自场景scenario机制通过PROVIDER_MOCKER_SCENARIO环境变量在进程启动前选择行为。合法的取值集合在 settings.py 中硬编码为{default, memory, looper, hallucination, toolcall, cli}非法值会直接抛出ValueError。值行为default原生协议回声echo、Router Flow planner/worker 夹具与协议标记protocol markersmemory完整消息回声、确定性的记忆事实提取与查询改写looper固定 ratings/confidence/fusion 响应与 token 计数提供/test/calls与/test/resethallucination基于关键字选择的 grounded 或故意不一致inconsistent文本toolcallWeb 搜索工具往返调用、故意不一致的答案与创造性的绕过行为cli应答ok、Provider base-path 处理与授权金丝雀authorization canary观察场景机制的选择逻辑集中在 scenarios.py 的respond_to_scenario它根据settings.scenario分发到looper、MemoryScenario、hallucination_text或toolcall_message等实现。需要特别注意的是场景只作用于 Chat Completions 行为其余原生端点保留各自的协议夹具。4.2 模型选择与授权金丝雀PROVIDER_MOCKER_MODEL选择GET /v1/models通告的模型默认值为openai/gpt-oss-20b见 settings.py响应体保留请求中携带的模型名。PROVIDER_MOCKER_EXPECT_AUTHORIZATION持有期望的 Bearertoken。请求必须携带Authorization: Bearer token匹配成功时日志输出authorization-canary-received且不会暴露 token 本身。CLI 场景还会记录收到的请求路径并接受以/chat/completions结尾的带前缀路径。4.3 延迟注入与影子控制PROVIDER_MOCKER_RESPONSE_DELAY_MS在原生响应前注入异步可控延迟。settings.py中的apply_fixture_delay会校验该值必须为非负数若为 0 则跳过等待。PROVIDER_MOCKER_SHADOW_CONTROLtrue启用/debug/shadow/{scenario}支持timeout、malformed、queue三种影子场景POST /reset接受healthy、hold或malformedPOST /release释放被挂起的请求。挂起hold请求在 60 秒后过期并递增一个可观测的过期计数器、返回 HTTP 504。4.4 协议标记输入Protocol Markers在 Chat Completions 请求内容中放入以下“魔法标记”即可触发对应的故障/特殊行为无需切换场景标记行为__mock_tool_call__触发工具调用__mock_structured_output__结构化 schema 回声__mock_provider_error__返回 HTTP 429__mock_incomplete_stream__不完整 SSE 流__mock_midstream_error__流中段部分输出错误__mock_protocol_matrix__Messages 端点专属协议矩阵行为这些标记让 Router 契约测试可以精确复现超时、限流、断流等边界情况是 E2E 测试如 e2e/testing/run_all_tests.py 对应的测试套件稳定可复现的关键。五、两种本地运行方式除了 Kubernetes 部署模拟器也可以直接在开发机上运行方式一Python 虚拟环境运行参考 tools/test/services/provider-mocker/README.mduv venv .venv --python 3.11 uv pip install --python .venv/bin/python -r requirements-dev.txt .venv/bin/python -m provider_mocker --host 127.0.0.1 --port 8000 .venv/bin/python -m pytest注意以上命令需要在tools/test/services/provider-mocker目录下执行从其他工作目录运行时需要将该目录加入PYTHONPATH或安装该包。环境要求Python 3.11tooling.mk中的引导脚本会做版本校验。方式二Docker 运行make docker-run-provider-mocker # 映射 127.0.0.1:8000可传 PROVIDER_MOCKER_SCENARIO / PROVIDER_MOCKER_MODEL make docker-test-provider-mocker # 无网络模式下启动容器并断言 /health 与 /v1/models 可达从 tools/make/docker.mk 可以看到docker-test-provider-mocker会在--network none下启动容器并轮询就绪然后通过urllib请求/v1/models验证镜像失败时打印容器日志——这是一个不占宿主端口、无需下载模型的镜像冒烟测试。5.1 Dockerfile 与依赖锁定provider-mocker/Dockerfile 基于python:3.11-slim固定 sha256 摘要构建上下文为tools/test/services/provider-mocker目录仅拷贝锁定的requirements.txt与provider_mocker/运行时包排除测试、文档和本地虚拟环境并以非 root 用户USER 65532:65532运行入口为python -m provider_mocker --host 0.0.0.0 --port 8000。依赖更新后需要重新生成两份锁文件uv pip compile requirements.in -o requirements.txt uv pip compile requirements-dev.in -o requirements-dev.txt六、真实调用链从 kind 部署到 Router 契约测试把上面所有环节串起来一个典型的验证链路是make docker-build-provider-mocker构建确定性后端镜像kubectl apply -k deploy/kubernetes/provider-mocker部署到 kindkubectl port-forward service/provider-mocker 8000:8000暴露到本机Router 或测试客户端以http://127.0.0.1:8000作为 OpenAI/Anthropic 兼容 base URL 发起请求通过PROVIDER_MOCKER_SCENARIO控制返回行为通过/debug/last-request校验 Router 发出的原始请求是否符合契约通过x-vsr-test-session-id头隔离测试会话。仓库中的 E2E 测试套件正是这样使用的例如test-e2e-vllm目标tools/make/build-run-test.mk会提示先用make start-provider-mocker启动确定性后端幻觉检测测试tools/make/build-run-test.mk则以PROVIDER_MOCKER_SCENARIOhallucination在 8002 端口启动模拟器并用curl /health确认就绪后再运行测试。因此Provider Mocker 是整个 Semantic Router E2E 验证体系中稳定、可复现的 Provider 基准。七、小结与适用边界Provider Mocker 的 Kubernetes 部署方案总结如下本地 kind 集群make docker-build-provider-mocker→kind load docker-image→kubectl apply -k deploy/kubernetes/provider-mocker→port-forward清单原样可用远程集群必须替换镜像为已发布的 digest 并把imagePullPolicy改为IfNotPresent行为控制PROVIDER_MOCKER_SCENARIO六种场景、PROVIDER_MOCKER_MODEL、PROVIDER_MOCKER_EXPECT_AUTHORIZATION、PROVIDER_MOCKER_RESPONSE_DELAY_MS、PROVIDER_MOCKER_SHADOW_CONTROL以及请求体中的协议标记适用场景Router 契约测试、协议兼容性验证、故障注入与本地开发联调边界它模拟的是协议行为而非模型质量固定 PNG 只用于验证图像分帧与解码需要真实小模型推理时应改用 tools/test/services/tiny-model 的 Qwen3-0.6B runner。依赖的完整环境变量定义可继续查阅 settings.py场景行为细节可查阅 scenarios.py 与对应的 test_scenarios.py部署清单源码位于 deploy/kubernetes/provider-mocker。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Paseo SDK Provider 指南模型选择、Provider 发现与 Agent 会话配置Paseo SDK Provider 指南模型选择、Provider 发现与 Agent 会话配置 导读 本文基于 Paseo TypeScript SDKOnyx Terraform Provider 数据源 onyx_llm_providers查询全部 LLM Provider 与部署默认模型的完整指南Onyx Terraform Provider 数据源 onyx_llm_providers 查询全部 LLM Provider 与部署默认模型的完整指南 oAI 应用大模型RAGAI Agent后端前端GHelper 轻量性能控制工具3 分钟把奥创中心的后台服务砍到零GHelper 轻量性能控制工具3 分钟把奥创中心的后台服务砍到零 你的奥创中心是不是又要转圈了一堆后台服务常驻上 GB 内存被吃掉更新还偶尔抽风。 根桌面应用系统编程上一篇htmx 实战巴黎 2024 奥运会网络自动化平台与 AI 友好型超媒体开发下一篇夜莺 Nightingale AI Agent 的 Guided Follow-up 提示词机制让每一次回答都以可执行的下一步收尾创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考