后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载导读本文基于开源项目 semantic-routervLLM 语义路由项目官方文档完整讲解如何将 Qdrant 源码中的底层实现逻辑。前置条件部署前需要准备Docker本机已安装 Docker 守护进程或Kubernetes 集群已配置好kubectl若选择 Kubernetes 的 Helm 安装方式还需Helm 3.x。使用 Docker 部署 Qdrant快速启动文档给出的标准做法是先创建一个共享 Docker 网络vllm-sr-network再让 Qdrant 和 Router 都接入该网络这样 Router 可以直接通过 Docker DNS 以服务名访问 Qdrant 的gRPC 端口6334而宿主机上只需要暴露 HTTP 端口用于健康检查docker network inspect vllm-sr-network /dev/null 21 || \ docker network create vllm-sr-network docker run -d --name qdrant \ --network vllm-sr-network \ -p 127.0.0.1:6333:6333 \ qdrant/qdrant:latest启动后验证 Qdrant 是否就绪curl http://localhost:6333/healthz/healthz返回{status:ok}或 HTTP 200即表示服务正常。这里6333是 Qdrant 的 REST/健康检查端口仅绑定在127.0.0.1回环地址上Router 走的是共享网络内的 gRPC 端口6334无需发布到宿主机这也避免了将向量数据库端口暴露到外部网络。带持久化的部署上面的命令未挂载数据卷容器删除后数据即丢失。官方文档提供了挂载命名卷qdrant-data到/qdrant/storageQdrant 官方镜像的默认数据目录的写法docker run -d --name qdrant \ --network vllm-sr-network \ -p 127.0.0.1:6333:6333 \ -v qdrant-data:/qdrant/storage \ qdrant/qdrant:latest开启 API Key 认证生产或共享环境应启用认证。文档演示了先用openssl生成一个随机 64 位十六进制 Key再通过环境变量QDRANT__SERVICE__API_KEY注入容器export QDRANT_API_KEY$(openssl rand -hex 32) docker run -d --name qdrant \ --network vllm-sr-network \ -p 127.0.0.1:6333:6333 \ -v qdrant-data:/qdrant/storage \ -e QDRANT__SERVICE__API_KEY$QDRANT_API_KEY \ qdrant/qdrant:latest启用认证后Router 配置中每个Qdrant 连接块都需要引用同一个 Keyapi_key: ${QDRANT_API_KEY}关键安全原则文档原文要点Key 必须保留在进程环境变量或 Kubernetes Secret中严禁把明文 API Key 写死在 Router 配置文件里当 Qdrant 服务端未开启认证时应省略api_key字段留空或省略均可见 config/runtime/response-cache/qdrant.yaml 中的示例api_key: 文档中的 Docker 示例统一使用latest镜像标签仅适合短期评估共享或生产部署应固定发布的 Qdrant 版本号或镜像 digest。网络与主机名的约定上文配置中的主机名qdrant是 Docker 在vllm-sr-network网络内的DNS 名称不是宿主机地址如果 Router 以自定义 stack 名称启动例如VLLM_SR_STACK_NAMEteam-a vllm-sr serve网络名会变为team-a-vllm-sr-network此时应将 Qdrant 挂到同名网络并把配置中的host换成对应的可解析主机名端口6334只映射到容器 gRPC 端口宿主上无需发布Router 通过共享网络直连即可。在 Kubernetes 中部署 Qdrant使用 Helm Chart文档给出的命令直接使用 Qdrant 官方 Helm Chart并显式指定了命名空间和持久卷大小helm repo add qdrant https://qdrant.github.io/qdrant-helm helm repo update helm install qdrant qdrant/qdrant \ --namespace vllm-semantic-router-system --create-namespace \ --set persistence.size10Gi--create-namespace会在安装时自动创建vllm-semantic-router-system命名空间--set persistence.size10Gi指定 PVC 容量为 10Gi。使用 StatefulSet 手动部署对于希望完全掌控清单不用 Chart的场景文档提供了完整的 StatefulSet Headless Service 组合。核心要点Qdrant 是有状态服务每个 Pod 需要独立稳定的存储因此使用StatefulSet而非 Deployment同时暴露两个端口6333REST/健康检查与6334gRPCRouter 实际使用的端口通过volumeClaimTemplates为每个副本动态申请10Gi的持久卷Service 使用clusterIP: None的Headless 模式与 StatefulSet 配合提供稳定的 Pod 身份。完整 YAML 如下文档原文完整继承apiVersion: apps/v1 kind: StatefulSet metadata: name: qdrant namespace: vllm-semantic-router-system spec: serviceName: qdrant replicas: 1 selector: matchLabels: app: qdrant template: metadata: labels: app: qdrant spec: containers: - name: qdrant image: qdrant/qdrant:latest ports: - containerPort: 6333 - containerPort: 6334 volumeMounts: - name: data mountPath: /qdrant/storage resources: requests: memory: 512Mi cpu: 250m limits: memory: 2Gi cpu: 1000m volumeClaimTemplates: - metadata: name: data spec: accessModes: [ReadWriteOnce] resources: requests: storage: 10Gi --- apiVersion: v1 kind: Service metadata: name: qdrant namespace: vllm-semantic-router-system spec: selector: app: qdrant ports: - name: rest port: 6333 targetPort: 6333 - name: grpc port: 6334 targetPort: 6334 clusterIP: None注意这个 StatefulSet 是无认证的评估示例。文档明确要求共享或生产集群必须固定 Chart 或镜像版本、通过 Kubernetes Secret 配置 API Key、在 Qdrant 与 Router 两侧同时启用 TLSapi_key/use_tls绑定、用 NetworkPolicy 限制访问并为持久卷定义备份与恢复流程。配置 Router 接入 QdrantQdrant 在 semantic-router 中承载四种能力每一类都有独立的配置块与专属字段。所有连接块都通过gRPC 端口 6334通信并共享host、port、可选api_key、use_tls四个基础字段。语义缓存Semantic Cache当请求命中相似度阈值内的历史响应时Router 直接复用缓存结果可显著降低重复推理成本global: stores: response_cache: enabled: true backend_type: qdrant similarity_threshold: 0.90 ttl_seconds: 7200 embedding_model: mmbert qdrant: host: qdrant # Service name or hostname port: 6334 use_tls: false collection_name: semantic_cache connect_timeout: 10字段说明similarity_threshold: 0.90缓存命中所需的余弦相似度阈值值越大要求越严格ttl_seconds: 7200缓存条目存活时间秒2 小时embedding_model: mmbert用于查询向量化的嵌入模型connect_timeout: 10连接超时秒。源码佐证在 qdrant_cache.go 中NewQdrantCache会将port缺省补为6334port 0时、collection_name缺省补为semantic_cache随后用qdrant.NewClient建立 gRPC 客户端并依次执行CheckConnection内部通过ListCollections探测连接见 CheckConnection 实现和ensureCollection——若semantic_cache集合不存在会以Distance_Cosine距离度量和 HNSW 参数M16、EfConstruct64自动创建集合并给request_id字段建立 Keyword 索引见 ensureCollection 实现。也就是说 Router 启动时会自动完成集合的初始化无需手工在 Qdrant 侧建集合。该配置块的完整字段结构对应源码中的QdrantConfigruntime_config.go字段包括host、port、api_key、use_tls、connect_timeout、collection_name。Agentic 记忆Agentic Memory记忆存储让 Router 在会话中携带历史事实与上下文。配置如下global: stores: memory: enabled: true backend: qdrant qdrant: host: qdrant port: 6334 collection: agentic_memory dimension: 256 # mmbert: 64, 128, 256, 512 or 768 embedding_model: mmbert default_retrieval_limit: 5 default_similarity_threshold: 0.30字段说明collection: agentic_memory记忆集合名。注意这里用的是collection而非缓存的collection_namedimension: 256向量维度。注释标明 mmbert 模型支持64、128、256、512 或 768五种 Matryoshka 维度default_retrieval_limit: 5默认检索条数上限default_similarity_threshold: 0.30默认相似度阈值。维度校验逻辑务必注意dimension必须是嵌入模型实际提供的尺寸之一。若配置了其他尺寸Router 会记录日志Failed to create memory store: … Memory will be disabled并在无记忆状态下继续运行对应 router_memory.go 中的降级逻辑。源码层面StorageDimension会先校验显式配置的维度再回退到模型默认值mmbert 默认 256若存在已准备的嵌入 Provider 则调用ResolveDimension严格校验配置的维度必须是 Provider 通告的输出维度或 Matryoshka 支持的维度之一否则直接报错见 dimension.go 与 embedding.go。阈值校准提醒文档原文要点0.30只是普通余弦检索的起点值不是校准后的数值。每个嵌入模型与向量尺寸都有各自的分值区间应根据你自己的数据用「已答复问题、无关问题、更正后的事实」三类查询分别校准阈值。集合自动初始化NewQdrantStore会以余弦距离自动创建集合HNSWM16、EfConstruct64并为user_id、project_id、memory_typeKeyword与created_atInteger四个字段建立 Payload 索引供 List/排序查询使用见 qdrant_store.go。上传文档向量存储Uploaded Document Vector Store用于对用户上传的文档做向量化检索RAG 场景global: stores: vector_store: enabled: true backend_type: qdrant file_storage_dir: /var/lib/vsr/data embedding_model: multimodal embedding_dimension: 384 qdrant: host: qdrant port: 6334 use_tls: false connect_timeout: 10 collection_prefix: vsr_vs_ metadata_store: memory字段说明file_storage_dir上传文件落盘目录embedding_model: multimodal、embedding_dimension: 384文档嵌入模型及其向量维度维度必须与模型实际输出一致否则启动校验会失败collection_prefix: vsr_vs_集合名前缀每个上传的文档/存储体对应一个以该前缀开头的 Qdrant 集合metadata_store: memory文件注册表元数据后端。当多个 Router 副本需要看到同一份上传文件清单时应改用共享的持久化元数据存储如 postgres而不是内存。源码佐证QdrantVectorStoreConfig的CollectionPrefix注释标明默认值为vsr_vs_vectorstore.goNewQdrantBackend在未显式配置前缀时也会回退到这个默认值qdrant_backend.go。backend_type的合法值由validateVectorStoreBackendType限定为memory、milvus、llama_stack、valkey、qdrant之一且qdrant模式要求vector_store.qdrant.host必填vectorstore.go。路由重放存储Router Replay Store重放能力用于记录路由决策便于审计与回放调试global: services: router_replay: enabled: true store_backend: qdrant qdrant: host: qdrant port: 6334 collection_name: router_replay启用该全局配置即打开路由器级重放策略。只有当某个决策需要覆盖捕获或保留行为时才需要额外添加路由局部的router_replay插件——详见 Router Replay 插件教程文档原文内部链接已转为仓库根目录相对路径。源码佐证重放存储工厂newStorageBackend的case qdrant分支要求cfg.Qdrant非空否则报错支持的后端为memory、redis、postgres、milvus、qdrant见 factory.go。NewQdrantStore中端口缺省补6334、集合缺省为router_replay_recordsqdrant.go。该模式还支持async_writes异步写入缓冲通道容量 100见 qdrant.go。配置参考四个 Qdrant 绑定的字段差异文档强调四个绑定都接受host、port、可选api_key、use_tls但集合字段刻意设计得各不相同切勿把一个能力的字段抄到另一个能力能力集合字段其他 Qdrant 专属字段响应缓存Response cachecollection_nameconnect_timeoutAgentic 记忆Agentic memorycollectiondimension、connect_timeout上传文档向量存储Uploaded document vector storecollection_prefixconnect_timeout路由重放Router Replaycollection_name重放 schema 中无连接超时字段启用认证时统一使用${QDRANT_API_KEY}这类环境变量引用。最终请校验完整配置而不是从某个能力复制字段到另一个能力可通过仓库中的参考配置样例对照缓存块见 config/runtime/response-cache/qdrant.yaml其中也演示了host: localhost、api_key: 、collection_name: semantic_cache、connect_timeout: 10的完整字段形态RAG 插件的 Qdrant 后端示例见 config/fragments/plugin/rag/qdrant.yaml含backend: qdrant、top_k: 5、similarity_threshold: 0.78、reuse_cache_connection: true等实用参数。生产环境加固清单结合文档与源码生产部署应至少落实以下事项固定版本Docker 镜像与 Helm Chart 均不要用latest固定发布版本号或 digest认证与密钥管理API Key 通过环境变量或 Kubernetes Secret 注入配置文件只写${QDRANT_API_KEY}形式的引用绝不落明文TLS在 Qdrant 服务端与 Router 的api_key/use_tls绑定两侧同时启用use_tls: true走加密 gRPC网络隔离K8s 场景用 NetworkPolicy 限制 Qdrant 仅对 Router 命名空间开放 6334持久化与备份使用 PVCStatefulSet 已内置并为持久卷定义备份/恢复流程多副本元数据vector_store 的多副本部署改用持久化metadata_store如 postgres避免各自维护内存注册表阈值校准记忆检索阈值按实际数据的 cosine 分值区间校准不要长期使用默认的 0.30。总结至此你已经可以通过 Docker 或 KubernetesHelm/StatefulSet快速部署 Qdrant并分别为 semantic-router 的语义缓存、Agentic 记忆、文档向量存储和路由重放四种能力配置正确的连接参数。源码层面Router 会在启动时自动完成集合创建、索引建立与连接健康检查失败时按能力降级运行这大大降低了接入成本而collection_name/collection/collection_prefix的字段差异、dimension的严格校验以及 API Key/TLS 的安全配置则是保证这套后端稳定运行的关键细节。赞分享后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐Semantic Router 集成 Milvus分布式向量响应缓存的后端配置与运维实战Semantic Router 集成 Milvus分布式向量响应缓存的后端配置与运维实战 本指南讲解如何为 Semantic Router 接入 Milvus后端API网关模型推理服务AI Agent用 PostgresML 为 Auto-GPT 构建记忆后端向量存储与语义检索实战用 PostgresML 为 Auto GPT 构建记忆后端向量存储与语义检索实战 Auto GPT 是依赖 GPT 4 与外部软件和服务交互的开源自主 AI后端人工智能机器学习RAG向量数据库HedgeDoc 使用 WebDAV 作为图片存储后端环境变量配置与 Nextcloud 实战指南HedgeDoc 使用 WebDAV 作为图片存储后端环境变量配置与 Nextcloud 实战指南 HedgeDoc 支持将笔记中的图片上传存储到多种后端本后端前端云原生上一篇30分钟上手ADB调试用Douyin-Bot打造抖音自动化脚本下一篇React-Slingshot 终极指南InversifyJS vs TypeDI 依赖注入框架对比创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考