@mfui/openai-compatible

@mfui/openai-compatible 把兼容 Chat Completions 的 SSE 流转换成 MFUI 语义 SSE 流。

当 provider 返回 choices[].delta.content 这种 OpenAI Chat Completions 风格的 chunk 时，使用这个包。

createMFUIResponse()

根据上游 Chat Completions 流创建 MFUI 语义 SSE Response。

Import

import { createMFUIResponse } from '@mfui/openai-compatible';

Signature

function createMFUIResponse(
  source: OpenAICompatibleStreamSource,
  mfui: MFUIManifest,
  options?: OpenAICompatibleMFUIResponseOptions,
): Response

入参

名称	类型	是否必填	默认值	描述
source	OpenAICompatibleStreamSource	是	无	Provider Response、response body stream，或 null。
mfui	MFUIManifest	是	无	当前请求可用的组件。
options	OpenAICompatibleMFUIResponseOptions	否	{}	Response、parser、writer 和生命周期选项。

返回值

类型	描述
Response	输出 MFUI 语义 SSE 事件的 text/event-stream response。

示例

import { createMFUIPrompt } from '@mfui/server';
import { createMFUIResponse } from '@mfui/openai-compatible';

const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      {
        role: 'system',
        content: [
          'You are a helpful assistant.',
          createMFUIPrompt(mfui),
        ].join('\n\n'),
      },
      ...messages,
    ],
    stream: true,
  }),
});

return createMFUIResponse(upstream, mfui, {
  onMessage(message) {
    saveAssistantMessage(message);
  },
});

注意事项

Provider 处理失败时，返回的 MFUI stream 会输出 error 事件并关闭。传入 onError 时会调用它。

OpenAICompatibleStreamSource

createMFUIResponse()、readStream() 和 pipeMFUIStream() 接受的 source。

结构

type OpenAICompatibleStreamSource =
  | Response
  | ReadableStream<Uint8Array>
  | null

OpenAICompatibleMFUIResponseOptions

createMFUIResponse() 的选项。

字段	类型	是否必填	默认值	描述
close	boolean	否	true	Provider stream 结束时是否关闭 MFUI parser 和 writer。只有当其他流程会负责关闭 parser 时才设为 false。
parser	MFUIBlockParserOptions	否	{}	传给 createMFUIBlockParser() 的选项。
writer	MFUIStreamWriterOptions	否	{}	传给 createMFUIStreamWriter() 的选项。
responseInit	ResponseInit	否	{}	传给返回 Response 的 init 对象。
onMessage	MFUIMessageHandler	否	无	MFUI response 完成后，使用最终投影消息调用。
onError	MFUIErrorHandler	否	无	Provider stream 处理或 MFUI block 解析失败时调用。

readStream()

读取 Chat Completions SSE 事件，并产出 JSON chunk。

Import

import { readStream } from '@mfui/openai-compatible';

Signature

function readStream(
  source: OpenAICompatibleStreamSource,
): AsyncIterable<OpenAICompatibleStreamChunk>

入参

名称	类型	是否必填	默认值	描述
source	OpenAICompatibleStreamSource	是	无	Provider SSE source。

返回值

类型	描述
AsyncIterable<OpenAICompatibleStreamChunk>	解析后的 provider chunks。[DONE] 哨兵事件会被跳过。

OpenAICompatibleStreamChunk

writeMFUIStream() 消费的 provider chunk 结构。

字段	类型	是否必填	默认值	描述
choices	Array<{ delta?: Record<string, unknown> }>	否	无	Chat Completions choices。delta.content 字符串会追加到 MFUI block parser。
usage	Record<string, unknown>	否	无	Token 用量。prompt_tokens 映射为 inputTokens；completion_tokens 映射为 outputTokens。
[key]	unknown	否	无	MFUI 会忽略额外 provider 字段。

writeMFUIStream()

把解析后的 provider chunks 写入 MFUI block parser。

Import

import { writeMFUIStream } from '@mfui/openai-compatible';

Signature

function writeMFUIStream(
  stream: AsyncIterable<OpenAICompatibleStreamChunk>,
  parser: MFUIBlockParser,
  options?: OpenAICompatibleMFUIStreamOptions,
): Promise<void>

入参

名称	类型	是否必填	默认值	描述
stream	AsyncIterable<OpenAICompatibleStreamChunk>	是	无	解析后的 provider chunks。
parser	MFUIBlockParser	是	无	接收 provider 文本增量的 MFUI block parser。
options	OpenAICompatibleMFUIStreamOptions	否	{}	写入选项。

返回值

类型	描述
Promise<void>	Provider stream 完全消费，且 parser flush 或 close 后 resolve。

OpenAICompatibleMFUIStreamOptions

writeMFUIStream() 和 pipeMFUIStream() 的选项。

字段	类型	是否必填	默认值	描述
close	boolean	否	true	Provider stream 结束时是否调用 parser.close()。为 false 时会改为调用 parser.flush()。

pipeMFUIStream()

读取 provider SSE source，并写入 MFUI block parser。

Import

import { pipeMFUIStream } from '@mfui/openai-compatible';

Signature

function pipeMFUIStream(
  source: OpenAICompatibleStreamSource,
  parser: MFUIBlockParser,
  options?: OpenAICompatibleMFUIStreamOptions,
): Promise<void>

入参

名称	类型	是否必填	默认值	描述
source	OpenAICompatibleStreamSource	是	无	Provider SSE source。
parser	MFUIBlockParser	是	无	接收 provider 文本增量的 MFUI block parser。
options	OpenAICompatibleMFUIStreamOptions	否	{}	写入选项。

返回值

类型	描述
Promise<void>	Provider stream 消费完成后 resolve。