@ cascadeflow/ core (中文(简体) )

用于级联流的Script/JavaScript 库

智能AI模式串联成本优化.

在LLM上节省了40-85%的成本,并配有智能模型路由. 可用于Node.js,浏览器,和边缘环境.

安装

npm install @cascadeflow/core
# or
pnpm add @cascadeflow/core
# or
yarn add @cascadeflow/core

机能快速启动( V2.1)

import { cascadeflow } from '@cascadeflow/core';

// 1) Turn on in-process harness decisions + SDK auto-instrumentation
cascadeflow.init({ mode: 'enforce', budget: 0.5 });

// 2) Scope one run (global defaults are inherited)
const result = await cascadeflow.run({ maxToolCalls: 8 }, async (run) => {
  // Any OpenAI / Anthropic SDK calls made here are evaluated by the harness.
  return { runId: run.runId };
});

console.log(result);

快速启动

建议设置( Claude Haiku + GPT-5)

import { CascadeAgent } from '@cascadeflow/core';

const agent = new CascadeAgent({
  models: [
    {
      name: 'claude-haiku-4-5',
      provider: 'anthropic',
      cost: 0.001  // Fast, high-quality drafter
    },
    {
      name: 'gpt-5',
      provider: 'openai',
      cost: 0.00125  // Superior reasoning verifier (50% cheaper than GPT-4o!)
    }
  ]
});

const result = await agent.run('What is artificial intelligence?');

console.log(result.content);
console.log(`Cost: $${result.totalCost}`);
console.log(`Savings: ${result.savingsPercentage}%`);

质量配置

当级联使用具有质量阈值的起草者与核查者时控制:

// Recommended: Complexity-aware thresholds
const agent = new CascadeAgent({
  models: [
    { name: 'claude-haiku-4-5', provider: 'anthropic', cost: 0.001 },
    { name: 'gpt-5', provider: 'openai', cost: 0.00125 }
  ],
  quality: {
    confidenceThresholds: {
      simple: 0.6,      // "What is Python?" - Accept 60%+ confidence
      moderate: 0.7,    // "Compare Python vs Java" - Accept 70%+
      hard: 0.8,     // "Analyze quantum computing" - Accept 80%+
      expert: 0.85      // "Implement distributed cache" - Accept 85%+
    }
  }
});

快速配置选项 :

// Option 1: Use CASCADE_QUALITY_CONFIG (optimized for 50-60% acceptance)
import { CascadeAgent, CASCADE_QUALITY_CONFIG } from '@cascadeflow/core';
const agent = new CascadeAgent({
  models: [...],
  quality: CASCADE_QUALITY_CONFIG  // Lower threshold (0.40) = more cost savings
});

// Option 2: Simple flat threshold
const agent = new CascadeAgent({
  models: [...],
  quality: {
    threshold: 0.7,              // 70% confidence required (default)
    requireMinimumTokens: 10     // Minimum response length
  }
});

// Option 3: Use defaults (no quality config needed)
const agent = new CascadeAgent({
  models: [...]
  // Automatically uses threshold: 0.7
});

何时调整 :

• 下限(0.4-0.6):接受更多的草案 ——节省费用,质量略低
• 更高的阈值(0.8-0.9):接受的草稿较少 ——节省较少,质量最高
• 复杂意识: 最佳平衡 = 根据查询难度自动调整

GPT-5要求组织核查

要使用 GPT-5, 您的 OpenAI 组织必须经过验证 :

1. 转到 https://platform.openai.com/ settings/organization/general (中文(简体) )
2. 点击“ 验证组织”
3. 等待 ~ 15 分钟, 访问传播

立即动工: 上面的级联马上起作用! Claude Haiku处理75%的询问,GPT-5只在需要时打电话.

型号命名

两项命名公约都与CascadeFlow合作:

• claude-haiku-4-5 (用于预设,建议)
• claude-3-5-haiku-20241022 (Anthropic API格式) (中文(简体) )

库既接受格式,又正确引导.

仅限 OpenAI

const agent = new CascadeAgent({
  models: [
    { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015 },
    { name: 'gpt-5', provider: 'openai', cost: 0.00125 }  // Requires org verification
  ]
});

甚至轻松: 使用预设

不需要配置 - 只需导入一个预设 然后去:

import { CascadeAgent, PRESET_ULTRA_FAST, PRESET_BEST_OVERALL } from '@cascadeflow/core';

// Ultra-fast with Groq (5-10x faster than OpenAI)
const agent = new CascadeAgent(PRESET_ULTRA_FAST);

// Or best overall (Claude Haiku + GPT-4o-mini)
const agent = new CascadeAgent(PRESET_BEST_OVERALL);

const result = await agent.run('Your query here');

可用的预设 :

自定义预设 :

import { CascadeAgent, createPreset } from '@cascadeflow/core';

const agent = new CascadeAgent(
  createPreset({
    quality: 'strict',      // 'cost-optimized' | 'balanced' | 'strict'
    performance: 'fast',    // 'fast' | 'balanced' | 'reliable'
    includePremium: true    // Add premium tier (gpt-4o)
  })
);

高级特性

QQ 质量简介

控制质量验证, 并优化预定义配置文件, 用于不同的使用情形 :

import { CascadeAgent, QualityValidator } from '@cascadeflow/core';

// Strict Mode: Maximum quality with semantic validation
const strictAgent = new CascadeAgent({
  models: [...],
  cascade: {
    enabled: true,
    qualityConfig: {
      useProductionConfidence: true,
      strictMode: true,
      useSemanticValidation: true,
      minConfidence: 0.85,
      provider: 'openai',
    },
  },
});

// Or use factory methods
const strictValidator = QualityValidator.strict();
const prodValidator = QualityValidator.forProduction();    // Multi-signal confidence
const devValidator = QualityValidator.forDevelopment();     // Lenient for testing
const cascadeValidator = QualityValidator.forCascade();     // Optimized for 50-60% acceptance
const permissiveValidator = QualityValidator.permissive();  // Maximum throughput

可用的配置文件 :

• 严格: 85% 置信度+语义验证(最大质量)
• 生产: 70%的置信度与多信号估计(平衡)
• 发展: 50% 置信度, 最小字数( 快速重排)
• 连锁店: 40%的置信度,优化以节省费用(50-60%的接受草案)
• 允许性:30%的信心,最大吞吐量(最高储蓄)

* 完整实例

遥测和召回

以事件驱动调用监视级联操作 :

import { CascadeAgent, CallbackManager, CallbackEvent } from '@cascadeflow/core';

const callbackManager = new CallbackManager(true); // verbose=true

// Track query lifecycle
callbackManager.register(CallbackEvent.QUERY_START, (data) => {
  console.log(`Query started: "${data.query}"`);
});

callbackManager.register(CallbackEvent.COMPLEXITY_DETECTED, (data) => {
  console.log(`Complexity: ${data.data.complexity} (confidence: ${data.data.confidence})`);
});

callbackManager.register(CallbackEvent.DRAFT_ACCEPTED, (data) => {
  console.log(`Draft accepted! Savings: $${data.data.savings}`);
});

const agent = new CascadeAgent({
  models: [...],
  callbacks: callbackManager,
  cascade: { enabled: true },
});

可用事件 :

• QUERY_START 编号 : QUERY_COMPLETE - 查询生命周期
• COMPLEXITY_DETECTED - 查询复杂性分析
• CASCADE_DECISION - 例行决定
• QUALITY_VALIDATION - 质量检查
• DRAFT_ACCEPTED 编号 : DRAFT_REJECTED - 结果草案
• VERIFIER_CALLED - 验证者援引

* 完整实例

批处理

处理多个查询,包括进度跟踪和分析:

const queries = [
  'What is TypeScript?',
  'Explain async/await.',
  'What are design patterns?',
];

const batchResult = await agent.runBatch(queries, {
  strategy: BatchStrategy.SEQUENTIAL,
  continueOnError: true,
  onProgress: (completed, total, currentQuery) => {
    console.log(`[${(completed/total*100).toFixed(0)}%] ${completed}/${total}`);
  },
});

// Analyze results
console.log(`Success rate: ${(batchResult.successCount / queries.length * 100).toFixed(1)}%`);
console.log(`Total cost: $${batchResult.results.reduce((sum, r) => sum + (r.result?.totalCost || 0), 0)}`);
console.log(`Draft acceptance: ${batchResult.results.filter(r => r.result?.draftAccepted).length}`);

* 完整实例

QQ 路由器集成

具有复杂性分析和能力过滤功能的智能路由:

// PreRouter: Automatically routes based on query complexity
const simpleResult = await agent.run('What is 2 + 2?');
// → Uses draft model (simple query)

const complexResult = await agent.run(
  'Explain quantum computing theory with recent research references.'
);
// → Routes directly to best model (complex query)

// ToolRouter: Filters to tool-capable models
// Use a strict parser helper (see examples/nodejs/safe-math.ts).
const calculatorTool = createTool({
  name: 'calculator',
  description: 'Perform calculations',
  function: async ({ expression }) => safeCalculateExpression(expression),
});

const toolResult = await agent.run('Calculate 125 * 47', {
  tools: [calculatorTool],
});
// → Automatically excludes models without tool support

// Get router statistics
const stats = agent.getRouterStats();
console.log(stats.preRouter);  // Complexity-based routing stats
console.log(stats.toolRouter);  // Tool filtering stats

* 完整实例

QQ 用户配置和工作流程

管理用户级别、预算和优化偏好:

import { createUserProfile, createWorkflowProfile, TIER_PRESETS, WORKFLOW_PRESETS } from '@cascadeflow/core';

// Tier-based profiles
const freeProfile = createUserProfile({
  tier: TIER_PRESETS.free,  // Max budget: $0.01, Quality: 0.60
});

const premiumProfile = createUserProfile({
  tier: TIER_PRESETS.premium,  // Max budget: $0.10, Quality: 0.80
});

// Custom profile with optimization weights
const customProfile = createUserProfile({
  tier: { name: 'custom', maxBudget: 0.05, qualityThreshold: 0.75 },
  optimizationWeights: {
    cost: 0.5,    // 50% weight on cost
    speed: 0.3,   // 30% weight on speed
    quality: 0.2, // 20% weight on quality
  },
});

// Latency-aware profiles
const lowLatencyProfile = createUserProfile({
  tier: TIER_PRESETS.premium,
  latencyProfile: {
    maxTotalMs: 2000,      // 2 second total limit
    maxPerModelMs: 1000,   // 1 second per model
    preferParallel: true,  // Prefer parallel execution
    skipCascadeThreshold: 1500,
  },
});

// Use with agent
const agent = new CascadeAgent({
  models: [...],
  profile: premiumProfile,
  cascade: { enabled: true },
});

工作流程预设 :

• WORKFLOW_PRESETS.production - 高质量、合理的长期性
• WORKFLOW_PRESETS.realtime - 超低纬度,单一型号
• WORKFLOW_PRESETS.batch - 最大吞吐量,放松约束

* 完整实例

工厂方法

以自动配置方式简化代理创建 :

import { CascadeAgent } from '@cascadeflow/core';

// Auto-detect providers from environment variables
const envAgent = CascadeAgent.fromEnv({
  quality: 'production',  // 'strict' | 'production' | 'development'
});
// Checks for: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, etc.

// Create from user profile
const profileAgent = CascadeAgent.fromProfile({
  profile: premiumProfile,
  preferredModels: ['gpt-4o-mini', 'gpt-4o', 'claude-3-5-haiku-20241022'],
});

// Traditional manual configuration (full control)
const manualAgent = new CascadeAgent({
  models: [
    { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015 },
    { name: 'gpt-4o', provider: 'openai', cost: 0.00625 },
  ],
  cascade: { enabled: true },
});

福利:

• fromEnv(): 可用的自动检测提供者, 合理的默认
• fromProfile(): 多租户应用程序,每个用户配置
• 手动配置:全面控制生产需求

* 完整实例

* 强化流式

事件驱动、实时进展的流出:

const stream = agent.streamEvents('What is TypeScript?', {
  forceDirect: true,
});

for await (const event of stream) {
  switch (event.type) {
    case StreamEventType.START:
      console.log(`Streaming from: ${event.data.model}`);
      break;
    case StreamEventType.CHUNK:
      process.stdout.write(event.data.content);
      break;
    case StreamEventType.COMPLETE:
      console.log(`\nCost: $${event.data.totalCost?.toFixed(6)}`);
      console.log(`Time: ${event.data.timing?.total}ms`);
      break;
    case StreamEventType.ERROR:
      console.error(`Error: ${event.data.error}`);
      break;
  }
}

// Or collect the full result
import { collectResult } from '@cascadeflow/core';
const result = await collectResult(stream);
console.log(`Content: ${result.content}`);
console.log(`Model: ${result.modelUsed}`);

使用大小写 :

• 交互式聊天应用程序
• 实时内容生成
• 渐进内容显示
• 长式内容(文章、散文)

* 完整实例

特征

• 🎯 智能分层: 先自动尝试较小的模型
• 💰 成本优化: LLM 成本节省40-85%
• ⚡ 快点: 2- 10x 用小型模型更快的响应
• 🔀 多服务: OpenAI、Anthropic、Groq 和更多
• ✅ 质量验证: 有语义分析的多信号置信度
• 📊 遥测: 事件驱动的监测与回调
• 📦 批处理: 有分析的顺序处理
• 🔀 智能运行: 复杂和能力意识
• 👤 用户配置文件:基于等级的出入控制和预算
• 🌊 强化流化: 事件驱动的流出和进展
• 🏭 工厂方法: 以自动配置简化设置
• 📈 费用追踪: 详细的计量和节约分析

实例

所有实例均载于 examples/nodejs 目录 :

• 质量简介.ts - 质量鉴定概况(限制、生产、开发、级联、允许)
• 遥测回调 - 事件驱动的监测和召回
• 批处理.ts - 附有进度跟踪的批处理
• 路由器-集成.ts - 鲁特前与工具鲁特结合
• 用户配置-工作流程 - 用户简介、层级和工作流程
• 工厂方法 - 工厂方法(来自Env,来自Profile)
• 增强流化.ts - 随着活动而加强流动

以 :

npx tsx examples/nodejs/<example-name>.ts

文档

见 主要级联流文件 为完整的指南和实例.

许可证

麻省理工学院莱莫尼公司.