Stream 流式生成

Stream 是 v2.0 的单次流式生成能力，适用于摘要、翻译、结构化生成、代码生成等每次调用相互独立的场景。

需要多轮对话、工具注册、工具结果回传、Agent 状态管理时，请使用 Agent。

核心特征

主 API：generate(params)
输出结构：parts: Part[]
每次 generate() 会重置当前 parts
不维护多轮消息历史
支持 TextPart / ReasoningPart / ToolCallPart 等时序内容段

框架接入案例

框架	接入方式	示例
React	`useStream`	React 示例
Vue 3	`useStream`	Vue 3 示例
Vue 2	`StreamMixin`	Vue 2 示例
小程序	当前未导出 `StreamBehavior`	说明

快速使用

ReactVue3Vue2

tsx

import { useStream } from '@tencent/ssv-ai-sdk-react';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

const { parts, status, generate, stop } = useStream({
  api: {
    streamEndpoint: {
      url: 'https://your-api.com/stream',
    },
  },
  mode: 'stream',
  plugins: [new AGUIPlugin()],
});

await generate({ input: '请帮我总结这段内容' });

vue

<script setup>
import { useStream } from '@tencent/ssv-ai-sdk-vue';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

const { parts, status, generate, stop } = useStream({
  api: {
    streamEndpoint: {
      url: 'https://your-api.com/stream',
    },
  },
  mode: 'stream',
  plugins: [new AGUIPlugin()],
});
</script>

import { StreamMixin } from '@tencent/ssv-ai-sdk-vue2';
import { AGUIPlugin } from '@tencent/ssv-ai-sdk-plugin-agui';

export default {
  mixins: [
    StreamMixin({
      api: {
        streamEndpoint: {
          url: 'https://your-api.com/stream',
        },
      },
      mode: 'stream',
      plugins: [new AGUIPlugin()],
    }),
  ],
};

配置 Config

api.streamEndpoint

Stream 使用 streamEndpoint：

{
  api: {
    streamEndpoint: {
      url: 'https://your-api.com/stream',
      requestInterceptor(options) {
        options.headers = {
          ...options.headers,
          Authorization: 'Bearer your-token',
        };
        return options;
      },
      responseInterceptor(raw) {
        return raw;
      },
    },
  },
  mode: 'stream',
}

plugins

Stream 支持 Agent 插件体系，因此可以配合 AGUIPlugin 解析 AG-UI 事件流，并输出 parts。

plugins: [new AGUIPlugin()]

数据 State

interface StreamState {
  /** 当前生成的时序内容段 */
  parts: Part[];
  /** 错误信息 */
  error: AIErrorOptions | null;
  /** 任务状态 */
  status: 'idle' | 'loading' | 'success' | 'failed' | 'stopped';
  /** 助手细粒度状态 */
  assistantStatus: 'idle' | 'loading' | 'reasoning' | 'answering' | 'tool_calling';
}

Parts 时序内容段

Stream 的渲染核心是 parts。不同类型的 Part 按到达顺序追加：

type Part = TextPart | ReasoningPart | ToolCallPart | StepStartPart | FilePart | DataPart;

interface TextPart {
  type: 'text';
  text: string;
  status: 'streaming' | 'done';
}

interface ReasoningPart {
  type: 'reasoning';
  reason: string;
  status: 'streaming' | 'done';
}

interface ToolCallPart {
  type: 'tool_call';
  id: string;
  name: string;
  rawArgs: string;
  args: any;
  status: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
  result?: any;
  rawResult?: string;
  error?: string;
}

渲染原则：按 parts 顺序逐段渲染。

tsx

{parts.map((part, index) => {
  if (part.type === 'reasoning') return <div key={index}>{part.reason}</div>;
  if (part.type === 'text') return <p key={index}>{part.text}</p>;
  if (part.type === 'tool_call') return <ToolCard key={part.id} part={part} />;
  return null;
})}

方法 Action

方法	说明
`generate(params)`	发起一次流式生成，每次调用会重置 `parts`
`stop()`	停止当前生成
`setOptions(options)`	动态更新配置
`on(event, handler)`	监听事件
`off(event, handler)`	移除事件监听

与 Agent 的区别

特性	Stream	Agent
主要场景	单次流式生成	多轮 Agent 对话
输出	`parts`	`messages[].parts`
消息历史	不维护	维护
工具注册	不提供 `setTools`	提供 `setTools` / `setTool`
工具结果回传	不处理	通过 `toolExecuted` + `send({}, { type: 'tools' })`

Stream 流式生成 #

核心特征 #

框架接入案例 #

快速使用 #

配置 Config #

api.streamEndpoint #

plugins #

数据 State #

Parts 时序内容段 #

方法 Action #

与 Agent 的区别 #