@flutchai/flutch-sdk (英语)
与LangGraph和NestJS共同建设图形微服务的基础基础设施包.
概览
@flutchai/flutch-sdk 是一个自成一体的一揽子基础 将您的图形逻辑转换为生产准备的微服务。写出您的图形构建器,SDK处理其他一切:REST API,流线,健康检查,度量衡,回调,和版本.
SDK的设计是 框架不可知性 - 虽然它目前为有NestJS的LangGraph.js提供一等支持,但该架构允许在未来支持其他图表框架(LlamaIndex,自定义执行等).
包含什么
核心组成部分
- 通用图形模块 - 用于拖曳图服务的NestJS模块
- 抽象图形构建器 - 用于实施图表构建器的基础类
- 图形控制器 - 有标准终点的REST API控制器
- 回调控制器 - 交互式流动回调系统
接口类型( T)
- IGraph 服务 - 所有图表服务的标准接口
- IGraph 请求支付负荷 编号 : IGraph 反应负载 - 请求/答复合同
- IGraphRunnable 图形 - 图表执行配置
- 回调记录 编号 : 召回结果 - 回调系统类型
- 图表类型登记册 - 类型安全图定义
引擎组件
- 兰格芬 - LangGraph.js的整合
- 事件处理器 - 利用收集的衡量尺度对事件进行流处理
- ApiCall追踪器 - API呼叫追踪和消毒设施
校验 & Schemas
- 图表管理方案 - JSON Schema的图表清单
- 图表管理参数 - 明确验证公用事业
公用事业
- 图形TypeUtils - 版本分析和正常化
- 解析 :
global.simple::1.2.0→{ companyId, name, version } - 构建 :
build("global", "simple", "1.2.0")→global.simple::1.2.0 - 规范化: 处理遗留格式
- 解析 :
回调系统
交互式用户流动的完整回调基础设施:
- 基于托肯的回调注册
- ACL和安全检查
- 同上:
- 平台专用处理器(Web,Telegram)
- 审计记录
安装
npm install @flutchai/flutch-sdk
或者说
yarn add @flutchai/flutch-sdk
快速启动
SDK提供所有你需要的 快速启动生产准备图服务。 使用最小的设置,您可以得到一个功能完备的 NestJS 应用程序,与 REST API, 健康检查, 度量衡等等.
1. 创建您的图形构建器
import { Injectable } from "@nestjs/common";
import { AbstractGraphBuilder } from "@flutchai/flutch-sdk";
import { StateGraph, START, END } from "@langchain/langgraph";
@Injectable()
export class MyGraphBuilder extends AbstractGraphBuilder<"myGraph"> {
async buildGraph(config?: any): Promise<CompiledGraphFor<"myGraph">> {
// Define your graph logic
const graph = new StateGraph(MyState)
.addNode("process", async state => {
// Your processing logic
return { result: "processed" };
})
.addEdge(START, "process")
.addEdge("process", END)
.compile();
return graph;
}
}
2. 登记模块
import { Module } from "@nestjs/common";
import { UniversalGraphModule } from "@flutchai/flutch-sdk";
@Module({
imports: [
UniversalGraphModule.register({
graphType: "myGraph",
builder: MyGraphBuilder,
}),
],
})
export class AppModule {}
3. 启动您的申请
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(3000);
}
bootstrap();
就这样! 您的图形服务正在运行, 并有一个完整的 REST API .
你从盒子里得到什么
一旦你的服务运行,你就自动得到:
REST API 终点
SDK为即用控制器提供标准终点:
图表执行( E)GraphController(中文(简体) )
GET /health- 服务健康检查GET /graph-types- 列表支持的图表类型POST /generate- 非分流发电POST /stream- 服务器事件流POST /cancel/:requestId- 取消运行中的生成GET /registry- 查看已注册的图表GET /registry/stats- 书记官处统计
回调( N)CallbackController(中文(简体) )
POST /callback- 以象征性安全方式处理用户回调
UI 调度UIDispatchController(中文(简体) )
POST /api/graph/ui/dispatch- 向自定义 UI 端点发送请求GET /api/graph/:graphType/manifest- 用 UI 配置来显示图表GET /api/graph/:graphType/endpoints- 列出可用的 UI 端点GET /api/graph/catalog- 获取所有图表的目录
监测和可观察性
- 普罗米修斯度量衡
/metrics - 健康检查
@nestjs/terminus - 请求/答复记录
- API 呼叫跟踪与消毒
生产特点
- 头盔安全头
- 压缩中间软件
- 重新支持的回调系统
- OpenAPI/ Swagger 文档
- 处理和验证出错
API 使用示例
非结构化一代
curl -X POST http://localhost:3000/generate \
-H "Content-Type: application/json" \
-d '{
"requestId": "req-123",
"graphType": "myGraph",
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'
流出生成( SSE)
curl -X POST http://localhost:3000/stream \
-H "Content-Type: application/json" \
-d '{
"requestId": "req-456",
"graphType": "myGraph",
"messages": [
{ "role": "user", "content": "Tell me a story" }
]
}'
流返回 Server- Sent 事件 :
event: stream_event
data: {"type":"chunk","content":"Once upon"}
event: stream_event
data: {"type":"chunk","content":" a time"}
event: final
data: {"text":"Once upon a time...","attachments":[],"metadata":{}}
检查健康
curl http://localhost:3000/health
# Response: {"status":"healthy","timestamp":"2025-11-03T12:00:00.000Z"}
查看已注册的图表
curl http://localhost:3000/registry
# Response: {"total":1,"graphs":[{"graphType":"myGraph","builderName":"MyGraphBuilder"}]}
高级使用
使用多种工具查找代理工具
每一个绑定工具的图案 都被发送到每个回合。 有几十种工具是最快的,模型选择错误的工具往往超过30-50个。 打开工具搜索, 模型看到一些工具加 search_tools当任务需要时,找到其余的:
import { isToolSearchCall } from "@flutchai/flutch-sdk";
const modelConfig = {
modelId,
toolsConfig,
toolSearch: { enabled: true, alwaysLoaded: ["list_sites", "list_products"] },
};
const model = await modelInitializer.initializeChatModel(modelConfig);
// In the tools node: search runs in the SDK, against the same catalog.
if (isToolSearchCall(toolCall.name)) {
const { content } = await modelInitializer.searchTools(
modelConfig,
toolCall.args,
config
);
messages.push(
new ToolMessage({ content, tool_call_id: toolCall.id, name: toolCall.name })
);
}
将相同的配置传递给 searchTools 这个模型是用来命名目录的。 所找到的工具是从对话历史中读取的,所以图表没有额外状态. Claude通过Anthropic Messages API加载找到工具作为延后定义(defer_loading + 键 tool_reference),并保持即时缓存;其他提供方将核心工具加所找到的工具各转. alwaysLoaded 又取逗号分隔的字符串; maxResults (违约5)和 minTools (默认15)调取.
使用图形TypeUtils
import { GraphTypeUtils } from "@flutchai/flutch-sdk";
// Parse versioned graph types
const parsed = GraphTypeUtils.parse("global.simple::1.2.0");
// → { companyId: "global", name: "simple", version: "1.2.0" }
// Build graph type string
const fullType = GraphTypeUtils.build("company-123", "customRag", "2.0.0");
// → "company-123.customRag::2.0.0"
// Normalize legacy formats
const normalized = GraphTypeUtils.normalize("simple");
// → "global.simple"
// Extract version
const version = GraphTypeUtils.getVersion("global.rag::1.5.0");
// → "1.5.0"
验证图示
import { GraphManifestValidator } from "@flutchai/flutch-sdk";
const manifest = {
graphType: "myGraph",
title: "My Custom Graph",
description: "Does cool things",
// ... other fields
};
// Validate and get result
const result = GraphManifestValidator.validate(manifest);
if (!result.isValid) {
console.error(result.errors);
}
// Or throw on invalid
GraphManifestValidator.validateOrThrow(manifest);
处理串流事件
import { EventProcessor, StreamAccumulator } from "@flutchai/flutch-sdk";
@Injectable()
export class MyService {
constructor(private eventProcessor: EventProcessor) {}
async processStream(stream: any): Promise<IGraphResponsePayload> {
const accumulator = this.eventProcessor.createAccumulator();
for await (const event of stream) {
this.eventProcessor.processEvent(
accumulator,
event,
chunk => console.log(chunk) // Partial callback
);
}
return this.eventProcessor.getResult(accumulator);
}
}
建筑
软件包结构
src/
├── api/ # REST controllers and guards
├── bootstrap.ts # Service bootstrap utilities
├── callbacks/ # Callback system implementation
├── core/ # Core modules and builders
├── decorators/ # Custom decorators
├── endpoint-registry # Endpoint registration
├── engine/ # Graph execution engines
├── interfaces/ # TypeScript interfaces
├── schemas/ # JSON schemas
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
└── versioning/ # Version management
依赖关系
软件包没有内部依赖性,只依赖完善的外部库:
@nestjs/*- 建立可扩展服务器侧应用程序的NestJS框架@langchain/*- LLM集成和图解的LangChain生态系统ioredis- Redis客户端用于回调系统和缓存axios- 用于外部API呼叫的HTTP客户端zod- TypeScript- first schema 验证helmet, (中文(简体) ),compression- HTTP安全和性能中间软件
设计原则
- 自成一体 - 没有内部依赖,你需要的都是一个包
- 类型安全 - 所有组件的综合类型脚本定义
- 模块 - 只使用您需要的, 导入特定模块
- 生产准备 - 内部监测、健康检查和错误处理
- 框架整合 - 与LangGraph合并的无缝巢穴JS
快速启动
import {
UniversalGraphModule,
AbstractGraphBuilder,
} from "@flutchai/flutch-sdk";
import { Module } from "@nestjs/common";
@Injectable()
export class MyGraphBuilder extends AbstractGraphBuilder<"myGraph"> {
async buildGraph(config?: any) {
// Your LangGraph implementation
return compiledGraph;
}
}
@Module({
imports: [
UniversalGraphModule.register({
graphType: "myGraph",
builder: MyGraphBuilder,
}),
],
})
export class MyGraphModule {}
您的图表服务已经准备好 内置的REST API,健康检查,以及监控!
API 密码
主要出口
// Core
export { UniversalGraphModule, AbstractGraphBuilder };
// Interfaces
export {
IGraphService,
IGraphRequestPayload,
IGraphResponsePayload,
CallbackRecord,
CallbackResult,
};
// Engine
export { LangGraphEngine, EventProcessor, ApiCallTracer };
// Utilities
export { GraphTypeUtils, GraphManifestValidator };
// Types
export { IGraphTypeRegistry, CompiledGraphFor, BaseGraphState };
见 src/index.ts 用于完整导出列表.
发展
大楼
npm run build
测试
npm test
线性
npm run lint
特征
- 准备使用 NestJS 模块 图表服务
- 类型安全图定义 有类型脚本
- 内建的REST API 带有 OpenAPI 文档
- 回调系统 用于交互式用户流量
- 流程处理 有实时活动
- 健康检查 和普罗米修斯度量衡
- 重新调整整合 召回和缓存
- 多LLM支持 (OpenAI, Anthropic, Azure, Google, Mistral, Cohere) (英语)
- 图形版本 水电费
- 表面验证 用于图形配置
小蝶平台集成
SDK的设计旨在与 小蝶平台,将企业级能力从框出:
一行平台连接
UniversalGraphModule.register({
graphType: "myGraph",
builder: MyGraphBuilder,
flutch: {
apiKey: process.env.FLUTCH_API_KEY,
endpoint: "https://api.flutch.ai",
},
});
用蝶式平台获取什么
追踪和分析( A)
- 在所有图表中分布追踪
- 业绩计量和瓶颈检测
- 每个请求和模型的成本分析
- 调用跟踪
多频道用户界面
- Web、Telegram、Slack、WhatsApp 支持
- 跨频道的统一UI组件
- 频道特定适应
- 自定义品牌
治理和控制
- 限制税率和配额管理
- 用户和公司一级的限制
- 预算控制和警报
- 用法分析
测试和质量
- A/B 图文测试
- 接受测试自动化
- AI动力测试生成
- 回归测试
独立运行或与平台运行
SDK完全独立地进行自我托管的部署,或连接到Fluch平台的高级功能. 你选择.
主要惠益
即时服务部署
从图表逻辑到几分钟内部署微服务 不需要建立REST API,执行流线,或设置监控 - 都包括在内.
图形版本
内建支持版本您的图表 。 同时运行多个版本,测试新版本,安全地滚回.
框架的灵活性
目前支持LangGraph.js. (英语). 该架构旨在支持LlamaIndex等其它图表框架,确保您的投资是绝后的.
开发者经验
- 带有类型脚本的类型安全图定义
- 开发过程中的热重载
- OpenAPI/ Swagger 文档自动生成
- 全面处理错误
互动能力
- 回电: 在图形中添加交互式按钮和用户交互
- UI 端点: 为动态接口创建自定义的 UI 端点
- 流线: 与服务器事件实时响应
生产准备
- 用于监测的Prometheus计量标准
- 组织健康检查
- 重新支持的国家管理
- 安全头和压缩
使用大小写
- AI 代理微服务:部署自主代理作为可扩展服务
- 对话AI: 构建聊天机和虚拟助手
- RAG 系统: 执行检索增强的生成工作流程
- 多步骤工作流程: 管弦管式复合AI管线
- 互动助理: 创建带有回调和动态 UIs的代理
出版
软件包自动发布到 npmjs.org (韩语) 每次合并时 main 通过 GitHub 动作 .
如何运作
- 合并到
main,则 发布工作流程 运行 - 它读的版本来自
package.json - 如果一个标记
v{version}尚不存在——它创建了标记并发布到 npm - 如果标签已经存在——所有发布步骤都会被跳过( 独有)
出版用途 npm OIDC 信任出版 ——不需要npm标志性秘密. GitHub 动作跑道通过 OpenID Connect 直接以 npmjs.org 认证 .
规则
- 合并前跳出版本 如果
package.json版本匹配已有的 git 标签, 将不发布 - 使用语义版本 —— 说
MAJOR.MINOR.PATCH(例如:.0.2.14(中文(简体) )PATCH——错误修正,小改进MINOR——新的后向兼容特征MAJOR——打破更改
- 每个 PR 一个版本的凸起 ——尽可能将版本修改与功能/固定修改相隔离
发布新版本
# 1. Create a branch
git checkout -b chore/bump-version-X.Y.Z
# 2. Update version in package.json
# "version": "X.Y.Z"
# 3. Push and open a PR
git push origin chore/bump-version-X.Y.Z
# 4. Merge the PR — publishing happens automatically
链接
许可证
麻省理工学院