WeHomeBot/Ling项目API使用指南：构建智能对话工作流

项目概述

WeHomeBot/Ling是一个基于事件驱动的LLM（大语言模型）交互管理框架，它提供了构建复杂对话工作流的能力。通过模块化设计和丰富的API，开发者可以轻松实现多轮对话、流式响应、模板渲染等功能。

核心概念解析

1. 配置参数详解

ChatConfig 配置接口

interface ChatConfig {
  model_name: string;      // 指定使用的LLM模型名称
  endpoint: string;        // API服务端点地址
  api_key: string;         // 认证用的API密钥
  api_version?: string;    // 可选API版本号（部分提供商需要）
  session_id?: string;     // 自定义会话ID
  max_tokens?: number;     // 生成内容的最大token数
  sse?: boolean;           // 是否启用服务器推送事件
}

ChatOptions 选项接口

interface ChatOptions {
  temperature?: number;        // 控制生成随机性（0-1）
  presence_penalty?: number;   // 重复惩罚系数
  frequency_penalty?: number;  // 频率惩罚系数
  stop?: string[];            // 停止序列
  top_p?: number;             // 核心采样参数
  response_format?: any;       // 响应格式设置
  max_tokens?: number;        // 最大生成token数
  quiet?: boolean;            // 是否抑制输出
  bot_id?: string;            // 自定义机器人ID
}

Ling核心类使用指南

初始化实例

const ling = new Ling(config, options);

主要方法详解

1. 创建对话机器人

createBot(root?: string, config?: Partial<ChatConfig>, options?: Partial<ChatOptions>)

• root参数：设置JSON输出的根路径
• 示例：创建一个专门处理产品咨询的机器人

const productBot = ling.createBot('product_info', {
  model_name: 'gpt-4',
  temperature: 0.7
});

2. 服务器推送事件(SSE)配置

setSSE(sse: boolean)

SSE技术允许服务器主动向客户端推送数据，非常适合实时对话场景。启用后，客户端可以实时接收对话更新而无需轮询。

3. 工作流管理

• close()：优雅关闭所有连接
• cancel()：立即终止所有操作

事件系统

Ling继承自EventEmitter，提供丰富的事件监听：

ling.on('message', (msg) => {
  console.log('收到消息:', msg);
});

ling.on('finished', () => {
  console.log('所有操作已完成');
});

ChatBot类深度解析

核心方法

1. 提示词管理

// 添加系统提示（保留现有提示）
addPrompt(promptTpl: string, promptData?: Record<string, any>)

// 设置系统提示（替换现有提示）
setPrompt(promptTpl: string, promptData?: Record<string, string>)

提示词支持Nunjucks模板引擎，可实现动态内容：

bot.addPrompt(`你是一位{{ expertise }}专家`, {
  expertise: '金融投资'
});

2. 对话历史管理

// 添加历史记录
addHistory(messages: ChatCompletionMessageParam[])

// 设置历史记录
setHistory(messages: ChatCompletionMessageParam[])

3. 消息过滤

// 添加过滤器
addFilter(filter: ((data: any) => boolean) | string | RegExp | FilterMap)

// 清除所有过滤器
clearFilters()

对话流程控制

发起对话

async chat(message: string | ChatCompletionContentPart[])

示例：发送混合内容消息

await bot.chat([
  { type: 'text', text: '请分析这张图片' },
  { type: 'image_url', image_url: 'https://example.com/image.jpg' }
]);

事件监听

ChatBot提供细粒度的事件系统：

bot.on('string-response', (content) => {
  console.log('收到文本响应:', content);
});

bot.on('inference-done', (content) => {
  console.log('推理完成:', content);
});

最佳实践

1. 多机器人协作模式

// 创建专业领域机器人
const medicalBot = ling.createBot(null, { model_name: 'med-gpt' });
const legalBot = ling.createBot(null, { model_name: 'legal-gpt' });

// 设置各自专业提示
medicalBot.setPrompt('你是一位资深医学专家...');
legalBot.setPrompt('你是一位专业法律顾问...');

// 并行处理用户咨询
await Promise.all([
  medicalBot.chat('解释一下糖尿病症状'),
  legalBot.chat('劳动合同纠纷如何处理')
]);

2. 流式响应处理

ling.setSSE(true);

ling.on('message', (msg) => {
  // 实时更新UI
  updateChatUI(msg.data);
});

3. 错误处理机制

bot.on('error', (err) => {
  console.error('对话出错:', err);
  // 执行重试或降级逻辑
});

总结

WeHomeBot/Ling框架通过清晰的API设计和强大的事件系统，为开发者提供了构建复杂对话系统的能力。无论是简单的单轮对话，还是需要多机器人协作的复杂工作流，都能通过该框架高效实现。掌握本文介绍的核心概念和API使用方法，将帮助您快速构建基于LLM的智能对话应用。