ModelFusion

用于构建 AI 应用的 TypeScript 库。

简介 | 快速安装 | 使用示例 | 文档 | 更多示例 | 贡献 | modelfusion.dev

简介

[!重要] ModelFusion 已加入 Vercel，并正在被整合到 Vercel AI SDK 中。我们将把 ModelFusion 的精华部分引入 Vercel AI SDK，首先从文本生成、结构化对象生成和工具调用开始。请查看 AI SDK 以获取最新进展。

ModelFusion 是一个用于将 AI 模型集成到 JavaScript 和 TypeScript 应用中的抽象层，统一了常见操作的 API，例如 文本流式传输、对象生成 和 工具调用。它提供了支持生产环境的功能，包括可观ability 钩子、日志记录和自动重试机制。您可以使用 ModelFusion 构建 AI 应用、聊天机器人和智能代理。

• 供应商中立：ModelFusion 是一个非商业性的开源项目，由社区驱动。您可以将其与任何受支持的提供商一起使用。
• 多模态：ModelFusion 支持广泛的模型，包括文本生成、图像生成、视觉、文本转语音、语音转文本以及嵌入模型。
• 类型推断和验证：ModelFusion 在可能的情况下会推断 TypeScript 类型，并对模型响应进行验证。
• 可观ability 和日志记录：ModelFusion 提供观察者框架和日志记录支持。
• 弹性和稳健性：ModelFusion 通过自动重试、限流和错误处理机制确保无缝运行。
• 为生产环境而设计：ModelFusion 完全支持 tree-shaking，可在无服务器环境中使用，并且仅依赖最少的外部库。

快速安装

npm install modelfusion

或者使用入门模板：

• ModelFusion 终端应用入门
• Next.js、Vercel AI SDK、Llama.cpp 和 ModelFusion 入门
• Next.js、Vercel AI SDK、Ollama 和 ModelFusion 入门

使用示例

[!提示] 基础示例是入门的好方法，也可以与 文档 并行探索。您可以在 examples/basic 文件夹中找到它们。

您可以使用环境变量（例如 OPENAI_API_KEY）为不同的 集成 提供 API 密钥，或将它们作为选项传递给模型构造函数。

生成文本

使用语言模型和提示生成文本。如果模型支持，您可以对文本进行流式传输。如果模型支持（例如使用 llama.cpp），您可以使用图像进行多模态提示。

您可以使用 提示风格 来采用文本、指令或聊天形式的提示。

generateText

import { generateText, openai } from "modelfusion";

const text = await generateText({
  model: openai.CompletionTextGenerator({ model: "gpt-3.5-turbo-instruct" }),
  prompt: "写一篇关于机器人学会爱的短篇故事：\n\n",
});

提供商：OpenAI、兼容 OpenAI、Llama.cpp、Ollama、Mistral、Hugging Face、Cohere

streamText

import { streamText, openai } from "modelfusion";

const textStream = await streamText({
  model: openai.CompletionTextGenerator({ model: "gpt-3.5-turbo-instruct" }),
  prompt: "写一篇关于机器人学会爱的短篇故事：\n\n",
});

for await (const textPart of textStream) {
  process.stdout.write(textPart);
}

提供商：OpenAI、兼容 OpenAI、Llama.cpp、Ollama、Mistral、Cohere

带有多模态提示的 streamText

像 GPT 4 Vision 这样的多模态视觉模型可以将图像作为提示的一部分进行处理。

import { streamText, openai } from "modelfusion";
import { readFileSync } from "fs";

const image = readFileSync("./image.png");

const textStream = await streamText({
  model: openai
    .ChatTextGenerator({ model: "gpt-4-vision-preview" })
    .withInstructionPrompt(),

  prompt: {
    instruction: [
      { type: "text", text: "详细描述这张图片。" },
      { type: "image", image, mimeType: "image/png" },
    ],
  },
});

for await (const textPart of textStream) {
  process.stdout.write(textPart);
}

提供商：OpenAI、兼容 OpenAI、Llama.cpp、Ollama

生成对象

使用语言模型和模式生成类型化的对象。

generateObject

生成符合模式的对象。

import {
  ollama,
  zodSchema,
  generateObject,
  jsonObjectPrompt,
} from "modelfusion";

const sentiment = await generateObject({
  model: ollama
    .ChatTextGenerator({
      model: "openhermes2.5-mistral",
      maxGenerationTokens: 1024,
      temperature: 0,
    })
    .asObjectGenerationModel(jsonObjectPrompt.instruction()),

  schema: zodSchema(
    z.object({
      sentiment: z
        .enum(["positive", "neutral", "negative"])
        .describe("情感。"),
    })
  ),

  prompt: {
    system:
      "你是一名情感评估员。" +
      "请分析以下产品评论的情感：",
    instruction:
      "打开包装后，我闻到一股非常难闻的气味，" +
      "即使清洗后也没有消失。再也不会买了！",
  },
});

提供商：OpenAI、Ollama、Llama.cpp

streamObject

流式生成符合模式的对象。最终部分之前的不完整对象是未类型的 JSON。

import { zodSchema, openai, streamObject } from "modelfusion";

const objectStream = await streamObject({
  model: openai
    .ChatTextGenerator(/* ... */)
    .asFunctionCallObjectGenerationModel({
      fnName: "generateCharacter",
      fnDescription: "生成角色描述。",
    })
    .withTextPrompt(),

  schema: zodSchema(
    z.object({
      characters: z.array(
        z.object({
          name: z.string(),
          class: z
            .string()
            .describe("角色职业，例如战士、法师或盗贼。"),
          description: z.string(),
        })
      ),
    })
  ),

  prompt: "为一款奇幻角色扮演游戏生成3个角色描述。",
});

for await (const { partialObject } of objectStream) {
  console.clear();
  console.log(partialObject);
}

提供商：OpenAI、Ollama、Llama.cpp

生成图像

根据提示词生成一张图片。

import { generateImage, openai } from "modelfusion";

const image = await generateImage({
  model: openai.ImageGenerator({ model: "dall-e-3", size: "1024x1024" }),
  prompt:
    "西方邪恶女巫，以19世纪早期绘画风格呈现",
});

提供商：OpenAI (Dall·E)、Stability AI、Automatic1111

生成语音

将文本合成语音（音频）。也称为 TTS（文本转语音）。

generateSpeech

generateSpeech 将文本合成语音。

import { generateSpeech, lmnt } from "modelfusion";

// `speech` 是一个包含 MP3 音频数据的 Uint8Array
const speech = await generateSpeech({
  model: lmnt.SpeechGenerator({
    voice: "034b632b-df71-46c8-b440-86a42ffc3cf3", // Henry
  }),
  text:
    "女士们、先生们，晚上好！今晚广播里传来激动人心的消息，" +
    "滚石乐队发布了他们的首张新专辑《Hackney Diamonds》，这是近二十年来他们首次推出的新作品，" +
    "其中特别邀请了传奇人物 Lady Gaga、神奇的 Stevie Wonder，以及已故 Charlie Watts 的最后音符。",
});

提供商：Eleven Labs、LMNT、OpenAI

streamSpeech

generateSpeech 可以从文本或文本流中生成语音片段的流。根据模型的不同，这可以实现完全双工。

import { streamSpeech, elevenlabs } from "modelfusion";

const textStream: AsyncIterable<string>;

const speechStream = await streamSpeech({
  model: elevenlabs.SpeechGenerator({
    model: "eleven_turbo_v2",
    voice: "pNInz6obpgDQGcFmaJgB", // Adam
    optimizeStreamingLatency: 1,
    voiceSettings: { stability: 1, similarityBoost: 0.35 },
    generationConfig: {
      chunkLengthSchedule: [50, 90, 120, 150, 200],
    },
  }),
  text: textStream,
});

for await (const part of speechStream) {
  // 每个部分都是一个包含 MP3 音频数据的 Uint8Array
}

提供商：Eleven Labs

生成转录

将语音（音频）数据转录成文本。也称为语音转文本（STT）。

import { generateTranscription, openai } from "modelfusion";
import fs from "node:fs";

const transcription = await generateTranscription({
  model: openai.Transcriber({ model: "whisper-1" }),
  mimeType: "audio/mp3",
  audioData: await fs.promises.readFile("data/test.mp3"),
});

提供商：OpenAI (Whisper)、Whisper.cpp

嵌入值

为文本和其他值创建嵌入。嵌入是向量，用于在模型上下文中表示这些值的本质。

import { embed, embedMany, openai } from "modelfusion";

// 嵌入单个值：
const embedding = await embed({
  model: openai.TextEmbedder({ model: "text-embedding-ada-002" }),
  value: "起初，Nox不知道该如何处理这只小狗。",
});

// 嵌入多个值：
const embeddings = await embedMany({
  model: openai.TextEmbedder({ model: "text-embedding-ada-002" }),
  values: [
    "起初，Nox不知道该如何处理这只小狗。",
    "他敏锐地观察并吸收着周围的一切，从天空中的鸟儿到森林里的树木。",
  ],
});

提供商：OpenAI、与 OpenAI 兼容、Llama.cpp、Ollama、Mistral、Hugging Face、Cohere

分类值

将一个值分类到某个类别中。

import { classify, EmbeddingSimilarityClassifier, openai } from "modelfusion";

const classifier = new EmbeddingSimilarityClassifier({
  embeddingModel: openai.TextEmbedder({ model: "text-embedding-ada-002" }),
  similarityThreshold: 0.82,
  clusters: [
    {
      name: "politics" as const,
      values: [
        "they will save the country!",
        // ...
      ],
    },
    {
      name: "chitchat" as const,
      values: [
        "how's the weather today?",
        // ...
      ],
    },
  ],
});

// 强类型结果：
const result = await classify({
  model: classifier,
  value: "don't you love politics?",
});

分类器：EmbeddingSimilarityClassifier

文本分词

将文本拆分为标记，并从标记中重建文本。

const tokenizer = openai.Tokenizer({ model: "gpt-4" });

const text = "At first, Nox didn't know what to do with the pup.";

const tokenCount = await countTokens(tokenizer, text);

const tokens = await tokenizer.tokenize(text);
const tokensAndTokenTexts = await tokenizer.tokenizeWithTexts(text);
const reconstructedText = await tokenizer.detokenize(tokens);

提供商：OpenAI、Llama.cpp、Cohere

工具

工具是可由 AI 模型执行的函数（以及相关元数据）。它们对于构建聊天机器人和智能体非常有用。

ModelFusion 提供了多种开箱即用的工具：Math.js、MediaWiki 搜索、SerpAPI、Google 自定义搜索。你也可以创建自定义工具。

runTool

通过 runTool，你可以让兼容工具的语言模型（例如 OpenAI 聊天模型）调用单个工具。runTool 首先生成工具调用，然后使用参数执行该工具。

const { tool, toolCall, args, ok, result } = await runTool({
  model: openai.ChatTextGenerator({ model: "gpt-3.5-turbo" }),
  tool: calculator,
  prompt: [openai.ChatMessage.user("十四乘以十二等于多少？")],
});

console.log(`工具调用：`, toolCall);
console.log(`工具：`, tool);
console.log(`参数：`, args);
console.log(`是否成功：`, ok);
console.log(`结果或错误：`, result);

runTools

通过 runTools，你可以让语言模型生成多个工具调用以及文本。模型会决定需要调用哪些工具以及使用哪些参数。文本和工具调用都是可选的。此函数会执行这些工具。

const { text, toolResults } = await runTools({
  model: openai.ChatTextGenerator({ model: "gpt-3.5-turbo" }),
  tools: [calculator /* ... */],
  prompt: [openai.ChatMessage.user("十四乘以十二等于多少？")],
});

智能体循环

你可以使用 runTools 来实现一个智能体循环，该循环能够响应用户消息并执行工具。了解更多。

向量索引

const texts = [
  "彩虹是一种光学现象，在特定气象条件下可能会出现。",
  "它是由水滴中的光折射、内反射和色散引起的，从而在天空中呈现出连续的光谱。",
  // ...
];

const vectorIndex = new MemoryVectorIndex<string>();
const embeddingModel = openai.TextEmbedder({
  model: "text-embedding-ada-002",
});

// 更新索引——通常作为数据摄取流程的一部分进行：
await upsertIntoVectorIndex({
  vectorIndex,
  embeddingModel,
  objects: texts,
  getValueToEmbed: (text) => text,
});

// 从向量索引中检索文本片段——通常在查询时进行：
const retrievedTexts = await retrieve(
  new VectorIndexRetriever({
    vectorIndex,
    embeddingModel,
    maxResults: 3,
    similarityThreshold: 0.8,
  }),
  "彩虹与水滴"
);

可用的向量存储：Memory、SQLite VSS、Pinecone

文本生成提示风格

你可以使用不同的提示风格（如文本提示、指令提示或聊天提示）与 ModelFusion 的文本生成模型一起使用。这些提示风格可以通过 .withTextPrompt()、.withChatPrompt() 和 .withInstructionPrompt() 方法访问：

文本提示风格

const text = await generateText({
  model: openai
    .ChatTextGenerator({
      // ...
    })
    .withTextPrompt(),

  prompt: "写一篇关于机器人学会爱的短篇故事",
});

指令提示风格

const text = await generateText({
  model: llamacpp
    .CompletionTextGenerator({
      // 使用 llama.cpp 运行 https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF
      promptTemplate: llamacpp.prompt.Llama2, // 设置提示模板
      contextWindowSize: 4096, // Llama 2 的上下文窗口大小
      maxGenerationTokens: 512,
    })
    .withInstructionPrompt(),

  prompt: {
    system: "你是一位故事作家。",
    instruction: "写一篇关于机器人学会爱的短篇故事。",
  },
});

聊天提示风格

const textStream = await streamText({
  model: openai
    .ChatTextGenerator({
      model: "gpt-3.5-turbo",
    })
    .withChatPrompt(),

  prompt: {
    system: "你是一位著名的诗人。",
    messages: [
      {
        role: "用户",
        content: "给机器人起个名字吧。",
      },
      {
        role: "助手",
        content: "我建议叫罗比。",
      },
      {
        role: "用户",
        content: "写一篇关于罗比学会爱的短篇故事吧。",
      },
    ],
  },
});

图像生成提示模板

你也可以将提示模板与图像模型一起使用，例如使用一个基础的文本提示。这提供了一种简化的用法：

const image = await generateImage({
  model: stability
    .ImageGenerator({
      //...
    })
    .withTextPrompt(),

  prompt:
    "西方邪恶女巫，采用19世纪早期绘画风格",
});

提示模板	文本提示
Automatic1111	✅
Stability	✅

元数据和原始响应

ModelFusion 模型函数会返回丰富的响应，其中包括原始响应和元数据，只需将 fullResponse 参数设置为 true 即可。

// 访问原始响应（需要进行类型转换）和元数据：
const { text, rawResponse, metadata } = await generateText({
  model: openai.CompletionTextGenerator({
    model: "gpt-3.5-turbo-instruct",
    maxGenerationTokens: 1000,
    n: 2, // 生成2个完成内容
  }),
  prompt: "写一篇关于机器人学会爱的短篇故事：\n\n",
  fullResponse: true,
});

console.log(metadata);

// 将原始响应强制转换为 OpenAICompletionResponse 类型：
for (const choice of (rawResponse as OpenAICompletionResponse).choices) {
  console.log(choice.text);
}

日志记录与可观测性

ModelFusion 提供了一个 观察者框架 和 日志支持。你可以轻松追踪运行和调用层次结构，并且可以添加自定义的观察者。

在函数调用中启用日志记录

import { generateText, openai } from "modelfusion";

const text = await generateText({
  model: openai.CompletionTextGenerator({ model: "gpt-3.5-turbo-instruct" }),
  prompt: "写一篇关于机器人学会爱的短篇故事：\n\n",
  logging: "detailed-object",
});

文档

指南

• 模型函数
  • 生成文本
  • 生成对象
  • 生成图像
  • 生成语音
  • 生成转录
  • 文本分词
  • 嵌入值
  • 分类值
• 工具
  • 运行工具
  • 运行多工具
  • 智能体循环
  • 可用工具
  • 自定义工具
  • 高级功能
• 向量索引
  • 更新插入
  • 检索
• 文本块
  • 拆分文本
• 实用工具
  • API 配置
    • 基础 URL
    • 请求头
    • 重试策略
    • 限流策略
  • 日志记录
  • 观察者
  • 运行管理
  • 取消信号
• 实验性功能
  • 防护机制
  • 服务器
  • 成本计算
• 故障排除
  • 打包问题

集成

示例与教程

展示

API 参考

更多示例

基础示例

几乎涵盖了所有单独函数和对象的示例。强烈推荐作为入门参考。

StoryTeller

多模态, 对象流式传输, 图像生成, 文本转语音, 语音转文本, 文本生成, 对象生成, 嵌入

StoryTeller 是一款探索性的Web应用，用于为学龄前儿童创作简短的音频故事。

聊天机器人（Next.js）

Next.js 应用程序, OpenAI GPT-3.5-turbo, 流式传输, 取消处理

一个由 AI 助手驱动的 Web 聊天应用，基于 Next.js 实现。

PDF 聊天

终端应用, PDF 解析, 内存中的向量索引, 检索增强生成, 假设文档嵌入

向 PDF 文档提问，即可获得来自该文档的答案。

Next.js / ModelFusion 演示

Next.js 应用, 图像生成, 转录, 对象流式传输, OpenAI, Stability AI, Ollama

使用 ModelFusion 结合 Next.js 14（App Router）的示例：

• 图像生成
• 语音录制与转录
• 对象流式传输

双工语音流（使用 Vite/React 和 ModelFusion Server/Fastify）

语音流, OpenAI, Elevenlabs 流媒体, Vite, Fastify, ModelFusion 服务器

根据给定的提示，服务器会同时返回文本和语音流的响应。

BabyAGI 智能体

终端应用, 智能体, BabyAGI

TypeScript 实现的经典 BabyAGI 和 BabyBeeAGI。

维基百科智能体

终端应用, ReAct 智能体, GPT-4, OpenAI 函数, 工具

从维基百科获取问题答案，例如：“爱因斯坦和毕加索谁先出生？”

初中数学智能体

终端应用, 智能体, 工具, GPT-4

一个用于解答初中数学题的小型智能体。它使用计算器工具来求解题目。

PDF转推文

终端应用, PDF解析, 递归信息抽取, 内存向量索引, 风格示例检索, OpenAI GPT-4, 成本计算

从PDF中提取关于某个主题的信息，并以你自己的风格撰写一条推文。

Cloudflare Workers

Cloudflare, OpenAI

使用ModelFusion和OpenAI在Cloudflare Worker上生成文本。

贡献

贡献指南

请阅读ModelFusion贡献指南，了解开发流程、如何提出修复和改进建议，以及如何构建和测试你的更改。

ModelFusion 快速上手指南

ModelFusion 是一个用于构建 AI 应用的 TypeScript 库，它统一了文本生成、对象提取、图像生成、语音合成等多种 AI 操作的 API，并提供了生产环境所需的可观测性、日志记录和自动重试等功能。

重要提示：ModelFusion 已加入 Vercel 团队，其核心功能正在整合进 Vercel AI SDK。建议关注 Vercel AI SDK 以获取最新进展，但 ModelFusion 目前仍可正常使用。

环境准备

• 运行时环境：Node.js (推荐 v18+) 或支持 TypeScript 的浏览器环境
• 包管理器：npm, yarn, pnpm 或 bun
• 前置依赖：无特殊系统依赖，只需安装 Node.js 即可
• API Key：根据你选择的模型提供商（如 OpenAI, Ollama, LMNT 等），需提前准备好相应的 API Key，并通过环境变量配置或在代码中传入。

安装步骤

使用 npm 安装核心库：

npm install modelfusion

如果你希望快速开始，可以使用官方提供的 Starter 模板：

• 终端应用模板
• Next.js + Llama.cpp 模板
• Next.js + Ollama 模板

基本使用

以下示例展示如何使用 ModelFusion 调用不同模型。请确保已设置好对应服务商的环境变量（例如 OPENAI_API_KEY）。

1. 生成文本 (Generate Text)

调用大语言模型生成文本内容，支持流式输出。

import { generateText, openai } from "modelfusion";

const text = await generateText({
  model: openai.CompletionTextGenerator({ model: "gpt-3.5-turbo-instruct" }),
  prompt: "Write a short story about a robot learning to love:\n\n",
});

console.log(text);

流式输出示例：

import { streamText, openai } from "modelfusion";

const textStream = await streamText({
  model: openai.CompletionTextGenerator({ model: "gpt-3.5-turbo-instruct" }),
  prompt: "Write a short story about a robot learning to love:\n\n",
});

for await (const textPart of textStream) {
  process.stdout.write(textPart);
}

2. 生成结构化对象 (Generate Object)

利用 Schema 约束模型输出，直接获得类型安全的 JSON 对象。

import { zodSchema, generateObject, ollama } from "modelfusion";
import { z } from "zod";

const sentiment = await generateObject({
  model: ollama
    .ChatTextGenerator({
      model: "openhermes2.5-mistral",
      maxGenerationTokens: 1024,
      temperature: 0,
    })
    .asObjectGenerationModel(/* 配置对象生成模式 */),

  schema: zodSchema(
    z.object({
      sentiment: z
        .enum(["positive", "neutral", "negative"])
        .describe("情感倾向"),
    })
  ),

  prompt: {
    system: "你是一个情感分析助手。",
    instruction: "打开包裹后，我闻到了一股非常难闻的气味，即使清洗后也没有消失。再也不买了！",
  },
});

console.log(sentiment.object.sentiment);

3. 生成图像 (Generate Image)

调用绘图模型生成图片。

import { generateImage, openai } from "modelfusion";

const image = await generateImage({
  model: openai.ImageGenerator({ model: "dall-e-3", size: "1024x1024" }),
  prompt: "the wicked witch of the west in the style of early 19th century painting",
});

// image 包含生成的图片数据

4. 语音合成 (Text-to-Speech)

将文本转换为音频。

import { generateSpeech, lmnt } from "modelfusion";

const speech = await generateSpeech({
  model: lmnt.SpeechGenerator({
    voice: "034b632b-df71-46c8-b440-86a42ffc3cf3", // Henry
  }),
  text: "Good evening, ladies and gentlemen! Exciting news on the airwaves tonight.",
});

// speech 是包含 MP3 音频数据的 Uint8Array

5. 语音转文字 (Speech-to-Text)

将音频文件转录为文本。

import { generateTranscription, openai } from "modelfusion";
import fs from "node:fs";

const transcription = await generateTranscription({
  model: openai.Transcriber({ model: "whisper-1" }),
  mimeType: "audio/mp3",
  audioData: await fs.promises.readFile("data/test.mp3"),
});

console.log(transcription.text);

更多高级用法（如多模态输入、工具调用、自定义 Prompt 风格等）请参考 官方文档。