Skip to content

README.md

Latest commit

 

History

History
254 lines (200 loc) · 7.22 KB

README.md

File metadata and controls

254 lines (200 loc) · 7.22 KB
Raw

Nyro Standalone 模式

Standalone 模式通过单个 YAML 文件驱动，无需数据库，仅运行代理服务。适用于：

  • 容器化部署，配置通过 ConfigMap / Volume 挂载
  • CI/CD 管道中的临时代理
  • 嵌入式或边缘场景，资源受限
  • Config-as-Code 工作流
nyro-server --config config.yaml

配置文件示例

server:
  proxy_host: "0.0.0.0"
  proxy_port: 19530

providers:
  - name: openai
    default_protocol: openai
    endpoints:
      openai:
        base_url: https://api.openai.com/v1
    api_key: ${OPENAI_API_KEY}
    models_source: https://api.openai.com/v1/models

  - name: anthropic
    default_protocol: anthropic
    endpoints:
      anthropic:
        base_url: https://api.anthropic.com
    api_key: ${ANTHROPIC_API_KEY}

  - name: deepseek-openai
    default_protocol: openai
    endpoints:
      openai:
        base_url: https://api.deepseek.com/v1
    api_key: ${DEEPSEEK_API_KEY}

  - name: deepseek-anthropic
    default_protocol: anthropic
    endpoints:
      anthropic:
        base_url: https://api.deepseek.com/anthropic
    api_key: ${DEEPSEEK_API_KEY}

routes:
  - name: gpt-4o
    vmodel: gpt-4o
    targets:
      - provider: openai
        model: gpt-4o

  - name: claude-sonnet
    vmodel: claude-sonnet-4-20250514
    targets:
      - provider: anthropic
        model: claude-sonnet-4-20250514

  - name: deepseek-chat
    vmodel: deepseek-chat
    strategy: priority
    targets:
      - provider: deepseek-openai
        model: deepseek-chat
        priority: 1
      - provider: openai
        model: gpt-4o-mini
        priority: 2

  - name: text-embedding-3-small
    vmodel: text-embedding-3-small
    targets:
      - provider: openai
        model: text-embedding-3-small

最小配置

providers:
  - name: openai
    default_protocol: openai
    endpoints:
      openai:
        base_url: https://api.openai.com/v1
    api_key: sk-xxx

routes:
  - name: gpt-4o
    vmodel: gpt-4o
    targets:
      - provider: openai
        model: gpt-4o

简化写法（等价）

default_protocol / api_key 支持别名 protocol / apikey，单 endpoint 时 protocol 可省略（自动取 endpoints 的第一个协议）：

providers:
  - name: openai
    endpoints:
      openai:
        base_url: https://api.openai.com/v1
    apikey: sk-xxx

routes:
  - name: gpt-4o
    vmodel: gpt-4o
    targets:
      - provider: openai
        model: gpt-4o

规范名与别名不能同时出现（例如同时写 default_protocol 和 protocol），否则启动时报错。

配置字段说明

server

字段 默认值 说明
proxy_host 127.0.0.1 代理监听地址
proxy_port 19530 代理监听端口

--proxy-host / --proxy-port CLI 参数不覆盖 YAML 值，Standalone 模式代理地址完全由 YAML 控制。

providers[]

字段 别名 必填 说明
name — 是 Provider 名称，路由中通过此名称引用
default_protocol protocol 否 默认出口协议，必须在 endpoints 中有对应条目；省略时自动取 endpoints 声明顺序的第一个协议（多 endpoint 时会打印 WARN 日志建议显式设置）
endpoints — 是 协议 → 端点映射，key 为协议名（openai / anthropic / gemini），保留 YAML 声明顺序
api_key apikey 是 API 密钥，支持 ${ENV_VAR} 环境变量引用
use_proxy — 否 是否使用系统 HTTP 代理（默认 false）
models_source — 否 模型发现 URL 或 ai://models.dev/{vendor}
capabilities_source — 否 模型能力发现 URL 或 ai://models.dev/{vendor}
static_models — 否 静态模型列表，无 API 时的硬编码兜底

规范名与别名互斥：同一 provider 下同时出现 default_protocol + protocol，或 api_key + apikey，启动时直接报错。

routes[]

字段 别名 必填 说明
name — 是 路由名称
virtual_model vmodel 是 客户端请求的模型 ID（精确匹配）
type — 否 路由类型：chat（默认）/ embedding
strategy — 否 负载策略：weighted（默认）/ priority
targets — 是 目标列表（至少一个）
access_control — 否 是否启用访问控制（默认 false）。别名 enable_auth

routes[].targets[]

字段 必填 说明
provider 是 Provider 名称（需与 providers[].name 匹配）
model 是 实际模型 ID
weight 否 权重，weighted 策略下使用（默认 100）
priority 否 优先级，priority 策略下使用（默认 1，数字越小优先级越高）

缓存配置

Standalone 模式支持请求缓存，在 cache 段配置：

cache:
  exact:
    enabled: true
    default_ttl: 3600       # 缓存有效期（秒），默认 3600
    max_entries: 1000       # 最大缓存条数，默认 1000

  semantic:
    enabled: true
    embedding_route: text-embedding-3-small   # 用于语义向量化的路由名
    similarity_threshold: 0.92               # 语义相似度阈值，默认 0.92
    vector_dimensions: 1536                  # 向量维度，需与 embedding 模型匹配
    default_ttl: 600                         # 缓存有效期（秒），默认 600
    max_entries: 500                         # 最大缓存条数，默认 500

两种缓存策略：

策略 说明
exact 完全匹配缓存，相同请求体直接返回缓存结果
semantic 语义相似缓存，通过 embedding 向量计算相似度，相似请求复用缓存

多协议转发

当 Provider 声明了多个协议端点时，Nyro 按请求协议自动选择对应端点：

providers:
  - name: deepseek
    default_protocol: openai
    endpoints:
      openai:
        base_url: https://api.deepseek.com/v1
      anthropic:
        base_url: https://api.deepseek.com/anthropic
  • OpenAI 客户端请求 → 直接转发到 openai 端点
  • Anthropic 客户端请求 → 直接转发到 anthropic 端点
  • Gemini 客户端请求 → Provider 不支持，自动转换为 default_protocol（openai）后转发

Docker 部署

FROM rust:1.83 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release -p nyro-server

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/nyro-server /usr/local/bin/
COPY config.yaml /etc/nyro/config.yaml
EXPOSE 19530
CMD ["nyro-server", "--config", "/etc/nyro/config.yaml"]

proxy_host 在 YAML 中设置为 0.0.0.0 即可对容器外暴露。

与完整模式的差异

能力 完整模式 Standalone
Provider / Route 管理 Admin API 实时读写 编辑 YAML + 重启
Admin API 完整 不启动
WebUI 完整 不启动
请求日志 DB 存储 + WebUI 查看 仅 stdout
数据持久化 SQLite / Postgres / MySQL 无（进程重启从 YAML 恢复）
缓存 — exact + semantic 缓存（内存）
部署依赖 二进制 + 存储目录 二进制 + YAML 文件