# Ferry **Repository Path**: smartboot/ferry ## Basic Information - **Project Name**: Ferry - **Description**: Ferry（智渡）是一个基于 Feat 构建的 Java AI 网关：统一接入多模型，提供 OpenAI 兼容协议、token 限流与配额、语义缓存、内容安全与全链路可观测，支持私有化与信创部署。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-10-20 - **Last Updated**: 2026-10-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Ferry · 智渡 **把请求，渡到对的模型。** Ferry 是一个基于 [Feat](https://gitee.com/smartboot/feat) 构建的 **Java AI 网关**。 它把散落在各个业务系统里的模型调用收口到一个进程：统一协议、统一鉴权、统一配额、统一观测， 再按成本、延迟或权重，把每一个请求渡到最合适的模型。 不依赖 Envoy，不依赖 Istio，不依赖 Kubernetes —— `java -jar` 就能跑起来，一个 JVM 就是一道渡口。 [![Gitee star](https://gitee.com/smartboot/ferry/badge/star.svg?theme=dark)](https://gitee.com/smartboot/ferry/stargazers) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![Java](https://img.shields.io/badge/Java-8%2B-orange.svg)]() [![Status](https://img.shields.io/badge/status-early--stage-red.svg)]() > **项目状态：早期开发（M1）。** 接口与配置格式仍在演进，生产使用请等待 1.0。 > 本文档中的能力均标注了所属里程碑，不做超前宣传。 ## 为什么是 Ferry | | Ferry | 基于 Envoy 的 AI 网关 | |---|---|---| | 技术栈 | Java，与 Spring Cloud / Dubbo 同栈 | Go / C++，插件多为 Wasm | | 部署形态 | 单进程，`java -jar` 即可 | 通常依赖 K8s / Sidecar | | 插件开发 | 用 Java 写，团队现有能力直接复用 | 需要另学 Wasm / Go | | 私有化交付 | 一个 jar，适配信创环境 | 镜像与依赖较重 | | 适合谁 | Java 中台团队、政企私有云、集成商 | 云原生平台团队 | Ferry 不试图替代 Ingress 网关。它只做一件事：**让 LLM 调用变得可管、可算、可查**。 K8s 入口交给 Higress / NGINX / F5，模型调用这一层交给 Ferry。 Ferry 不是从零写的： - **服务端用 [Feat Cloud](https://gitee.com/smartboot/feat)** —— 控制器、Bean 注入、AOT、异步响应都是现成的； - **上游调用用 Feat AI** —— `FeatAI.chatModel(...)` 统一发起调用，`ChatOptions` 抽象掉 OpenAI / Anthropic 的连接与协议差异。 数据面入口由 Controller 的 `/*` 路由返回 `RouterHandler` 承接——只有它能让框架把连接交给我们的处理器， 客户端断开时才能第一时间停止写回（上游取消还需要 Feat 给 `ChatModel` 一个可取消句柄）。 ## 设计目标 - **零改造接入**：对外提供 OpenAI 兼容 API，业务代码换一个 `base_url` 就能接进来； - **成本可见可控**：按租户 / Key / 模型计量 token，配额前置、账单可对； - **多模型可调度**：成本优先、延迟优先、权重、灰度、自动降级； - **流式不劣化**：SSE 全程透传，首字节附加延迟控制在毫秒级； - **全链路异步**：基于 Feat 的 AIO 与 `CompletableFuture`，线程数与连接数解耦，不阻塞 I/O 线程； - **单机可跑**：不强制依赖 K8s、不强制依赖外部组件，最小形态一个 JVM； - **私有化友好**：配置、密钥、审计全部本地化，适配信创软硬件。 ## 非目标 - 不做模型推理服务本身； - 不做 K8s Ingress / 南北向流量网关（与 Higress 是互补关系）； - 不做物联网协议接入（那是 [smart-mqtt](https://gitee.com/smartboot/smart-mqtt) 的领域）； - 不做通用规则引擎，业务逻辑请留在业务系统里。 ## 架构 ``` 业务应用 AI Agent 外部调用 └────────────────────┼────────────────────┘ │ HTTP / SSE ▼ ┌─────────────────┐ │ server │ 接入层：OpenAI 兼容 API └────────┬────────┘ ▼ ┌─────────────────┐ │ core │ 治理：route（其余 auth / quota / └────────┬────────┘ cache / guard / audit 为 M2+） ▼ ┌─────────────────┐ │ provider │ 适配：openai / anthropic └────────┬────────┘ / gemini / ollama ▼ 通义千问 · DeepSeek · 私有模型 · 自建推理 旁路：Redis（配额/缓存） · Milvus（向量） · OTel（链路） ``` 接入层由 **Feat Cloud** 装配（控制器 + `Router`），上游调用由 **Feat AI** 的 `ChatModel` 承担， 中间治理只有模型路由一层；鉴权、配额、缓存、内容安全按 Filter 链在 M2+ 依次接入。 ## 能力与里程碑 | 能力 | 说明 | 里程碑 | |---|---|---| | OpenAI 兼容入口 | `/v1/chat/completions`、`/v1/models`（其余端点返 501） | M1 | | 流式透传 | SSE 逐事件写回，不整包缓冲；断连即停止写回 | M1 | | 模型路由 | 模型 API（base-path 入口 + 模型名精确匹配）、变体池（一个模型名关联多个服务）、加权分流、降级 | M1 | | 多上游适配 | OpenAI 协议优先，再扩 Anthropic / Gemini / Ollama | M2 | | 熔断与健康检查 | 被动摘除 + 半开恢复 | M2 | | 鉴权 | API Key、租户隔离、IP 白名单、Key 级作用域 | M2 | | 配额与计量 | RPM / TPM / 并发 / 日预算，预扣 + 结算 | M3 | | 可观测 | 指标、追踪（OTel）、结构化审计日志 | M3 | | 语义缓存 | 精确缓存 + 向量相似缓存，按租户隔离 | M4 | | 内容安全 | 输入输出双向扫描，支持流式分段检测 | M4 | | 控制台 | 路由 / Key / 配额 / 监控的可视化管理 | M4 | | MCP 托管 | 基于 Feat 的 MCP Server，统一工具鉴权与审计 | M5 | | 集群化 | 无状态多节点 + 配置中心 + Redis 共享状态 | M5 | ## 快速开始 > **当前进度（M1）**：数据面主链路已可运行——`POST /v1/chat/completions` + 模型路由 > （模型 API / 变体池 / 加权分流 / 降级 / 首包超时），路由结果可从响应头 `X-Ferry-Route` 直接读到。 > 鉴权、配额、缓存、内容安全、审计、管理面尚未接入；上游只支持 `spec: openai`，转发端点只开 chat completions。 环境要求：JDK 8+、Maven 3.6+。 > Feat 尚未发布到 Maven 中央仓库。首次构建前，需要先在 [feat](https://gitee.com/smartboot/feat) 仓库（`2.4.3-SNAPSHOT`，即当前 `origin/master`）执行一次 `mvn -DskipTests install`，把 `feat-core` / `feat-cloud` / `feat-ai` 装进本地仓库。2.4.3 正式版发布后，`pom.xml` 的 `feat.version` 改回正式号即可。 从源码构建： ```bash git clone https://gitee.com/smartboot/ferry.git cd ferry mvn clean package -DskipTests java -jar target/ferry.jar --config conf/ferry.yaml ``` 发一个请求： ```bash curl http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "messages": [{"role": "user", "content": "你好"}], "stream": true }' ``` `model` 必须是入口（模型 API）里声明的模型名；未声明的名字回 404。 M1 还没有鉴权，`Authorization` 头传了也不会校验。 ## 配置示例 监听地址在 `src/main/resources/feat.yaml` 的 `server` 段（框架配置）；业务配置只有 `services` 与 `model-apis`——结构对标阿里云 AI 网关：模型 API 是客户端的调用入口 （`base-path` + 协议默认路由），一个模型名可以关联多个服务变体： ```yaml services: # 只管"怎么连"（阿里云：创建服务） - name: qwen base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: sk-demo-qwen timeout: 60s - name: deepseek base-url: https://api.deepseek.com/v1 api-key: sk-demo-deepseek model-apis: # 客户端的调用入口 - name: chat base-path: / # 路由 URL = base-path + /v1/chat/completions first-token-timeout: 60s models: # 请求体 model 名精确匹配 - name: qwen-plus providers: # 变体池：按 weight 分流，失败自动切 - service: qwen weight: 100 - service: deepseek model: deepseek-chat # 上游真实模型名，省略则与 name 相同 weight: 30 fallback: # 池子全挂后依次尝试 - service: deepseek model: deepseek-chat ``` 完整示例见 [conf/ferry.yaml](conf/ferry.yaml)，字段校验规则由启动时的 `ConfigLoader` 逐项报出。 ## 模块 ``` ferry/ ├── pom.xml ├── src/main/java/tech/smartboot/ferry/ │ ├── Ferry.java # 启动入口 │ ├── core/ # 配置快照、模型路由（纯内存，可裸测） │ ├── provider/ # 上游共享 I/O 线程组 │ └── server/ # Feat Cloud 装配、控制器、RouterHandler、转发 ├── src/main/resources/feat.yaml └── conf/ferry.yaml # 业务配置示例 ``` 只有一个模块，分层靠包路径：`core` 不依赖 Feat，`server` 依赖 `core` + `provider`， 所以选路逻辑可以脱网单测，转发逻辑只碰一个 `Forwarder`。 ## 参与贡献 - 提交 Issue： - 提交 PR 前请先开 Issue 对齐设计，避免大改返工。 ## License Ferry 遵循 **Apache-2.0** 协议开源，与 [Feat](https://gitee.com/smartboot/feat) 保持一致。 可以自由商用、修改、再分发；如需商业支持或私有化交付，可联系 smartboot。 --- **Ferry · 智渡** —— 把请求，渡到对的模型。