Skip to content

prompt.md

Latest commit

 

History

History
314 lines (219 loc) · 7.41 KB

prompt.md

File metadata and controls

314 lines (219 loc) · 7.41 KB

本文档用于向团队内部清晰说明：

  • 我们要做的是什么
  • 为什么要这样拆架构
  • 每一层分别解决什么问题
  • 如何一步步落地，而不是空想

一、核心愿景（一句话）

构建一个以「双向大模型 API 适配器」为核心的 LLM 基础设施平台，使任意模型 API 可以自由进出、统一治理，并在此之上实现可配置、可演进、可评估的模型选择与调度体系，从而在不牺牲效果的前提下大幅降低长期模型使用成本。

二、我们到底在解决什么问题？（给团队的共识）

2.1 现实问题（不是假设）

  1. 最强模型（如 Claude）确实最好，但太贵
    • 大量简单任务不需要顶级模型
    • 但人和 Agent 都很懒，最终导致“全量用最贵的”
  2. 现有 Agent / SDK 几乎不具备模型决策能力
    • 通常只能全局指定 model
    • 或极其粗糙的 rule
  3. 模型 API 协议高度碎片化
    • OpenAI / Anthropic / Gemini / 私有模型
    • 每接一个厂商都要重写一套逻辑
  4. 没有统一的网关层
    • 无法统一统计、评估、对比
    • 无法沉淀“哪个模型在什么任务上更划算”

2.2 我们的核心判断

  • 问题不在于“有没有好模型”
  • 而在于：

没有一个工程化、可插拔、可演进的 LLM API 中枢层，去承接“协议统一 → 治理 → 策略 → 智能调度”这整条链路

三、整体架构总览（先看全貌）

┌──────────────────────────────┐
│         Client / Agent        │
│  (IDE / Agent / SDK / App)    │
└──────────────▲───────────────┘
               │  统一出口 API（可配置格式）
               ▼
┌─────────────────────────────────────────┐
│           LLM API Gateway Server         │
│                                         │
│  ┌──────── Core: 双向 API 适配器 ──────┐ │
│  │  Inbound Adapter  →  IR  → Outbound │ │
│  └─────────────────────────────────────┘ │
│                                         │
│  ┌──────── Gateway 能力层 ─────────────┐ │
│  │  统计 / 日志 / 限流 / 观测          │ │
│  └─────────────────────────────────────┘ │
│                                         │
│  ┌──────── Strategy & Router 层 ───────┐ │
│  │  规则引擎 / LLM 决策 / 评分体系     │ │
│  └─────────────────────────────────────┘ │
└──────────────▲──────────────────────────┘
               │
               ▼
┌──────────────────────────────┐
│      多模型厂商 / 私有模型    │
└──────────────────────────────┘

四、核心一：双向 LLM API 适配器（基础设施核心）

这是整个系统最核心、最底层、最稳定的一层

4.1 核心能力定义

双向 API 适配器具备以下能力：

  1. 正向解析（Inbound）
    • 接收任意厂商 / 任意格式的 API 请求
    • 解析为统一的中间语义（IR）
  2. 反向生成（Outbound）
    • 将 IR 转换为任意厂商所需的 API 格式
  3. 出口格式可配置
    • 同一个中转站：
      • 对外可以是 OpenAI 协议
      • 也可以是 Anthropic / 私有协议

👉 本质：API 协议的“正反向编解码器”

4.2 设计原则（非常重要）

  • ❗ 不做模型选择
  • ❗ 不做成本判断
  • ❗ 不做智能决策

只做：

  • 协议解析
  • 语义统一
  • 协议生成

4.3 中间语义（IR）示意

interface LLMRequestIR {
  messages: Message[]
  tools?: Tool[]
  stream?: boolean
  generation?: GenerationConfig
  metadata?: Record<string, any>
  raw?: any
}

IR 是桥梁，不是抽象圣杯，允许不完美，允许透传。

4.4 Adapter 扩展机制

interface LLMAdapter {
  name: string

  parseRequest(req: any): LLMRequestIR
  buildRequest(ir: LLMRequestIR): any

  parseStream?(chunk: any): LLMStreamEvent
  parseError?(err: any): LLMErrorIR
}
  • 任意用户都可以编写 Adapter
  • 小众厂商 / 私有模型不需要官方支持

五、核心二：LLM 网关能力层（治理，而非智能）

基于双向 API 适配器，对“所有进出流量”做统一治理

5.1 这一层解决什么？

  • 调用次数统计
  • Token / 成本统计
  • 延迟 / 成功率
  • 错误类型分布
  • 请求日志与回放

特点：

  • 与模型选择无关
  • 与业务无关
  • 为上层策略提供“事实数据”

六、核心三：策略 & Router 层（真正的想象空间）

这是系统中变化最快、策略最灵活的一层

6.1 策略来源（三种）

1️⃣ 规则驱动（Rule-based）

- when:
    prompt.tokens < 1000
    task.type == "format"
  use: deepseek-chat

- when:
    prompt.contains("architecture")
  use: claude

特点：

  • 可控
  • 可解释
  • 适合早期

2️⃣ LLM 决策（Meta-LLM）

使用一个便宜模型来决定“该用哪个模型”

输入：

  • Prompt
  • 用户规则
  • 历史表现

输出：

{
  "model": "claude",
  "reason": "high complexity"
}

3️⃣ 混合策略（推荐）

  • 规则先行（硬约束）
  • LLM 决策兜底
  • 失败自动升级

6.2 评分与反馈体系（长期价值）

  • 自动评分：
    • 结构正确性
    • 编译 / 测试结果
  • 人工评分（可选）

这些数据将反向用于：

  • 模型性价比评估
  • 策略优化

七、客户端与使用方式设计

7.1 对客户端的承诺

  • 客户端无需理解多模型
  • 只需：
    • 一个 API Key
    • 一个 Base URL

7.2 客户端形态

  1. OpenAI-compatible API（优先）
  2. SDK（Node / Python）
  3. CLI / Agent Runtime

八、分层与权衡（给团队的关键说明）

层级 是否稳定 变化频率 是否开源优先
双向 API Adapter 极稳定 极低 是
Gateway 能力层 稳定 低 是
Strategy / Router 不稳定 高 可选
SaaS / UI 不稳定 高 否

九、落地路线（现实版）

Phase 1（基础设施）

  • 双向 API Adapter
  • OpenAI In / OpenAI Out
  • Claude / DeepSeek Out

Phase 2（网关）

  • 统计 / 日志 / 成本
  • 简单规则路由

Phase 3（智能）

  • Meta-LLM 决策
  • 自动升级 / 评分体系

十、总结（给团队的最后一句话）

我们不是在“做一个省钱技巧”，而是在构建：

LLM 时代的 API Gateway + 智能调度中枢。

双向 API 适配器是地基，其余一切都建立在它之上。

这套系统允许我们：

  • 今天只解决成本问题
  • 明天演进为智能系统
  • 后天成为多模型时代的基础设施