[RFC]useXAgent， useXChat，XRequest在真实请求场景下对流的支持

[kimteayon]

Summary

useXAgent， useXChat，XRequest在真实请求场景下对流的支持

Motivation

在服务群、样板间、业务中使用useXAgent， useXChat，XRequest发现对于真实请求的流解析、控制等都有欠缺，以及官网一些demo错误，因此对useXAgent， useXChat，XRequest做完善和修改。

Detailed Design & Example Usage

XRequest

ISSUE

1、作为最基础的数据请求方法XRequest 对fetch进行了封装 但没有提供终止的方法
2、在useXChat提供的打断输出demo是基于自定义request，同时是使用 readableStream 去做的，此实例只可读取一次就会被锁定，限制比较大一般不会用这个去做abort，建议使用AbortController。

API

在 XRequestCallbacks新增 onStream 返回 abortController(后续还可以扩展其他参数)。

Example Usage

 const abortController = useRef<AbortController>(null);

await exampleRequest.create(
      {
        messages: [{ role: 'user', content: 'hello, who are u?' }],
        stream: true,
      },
      {
        onSuccess: (messages) => {
          setStatus('success');
          console.log('onSuccess', messages);
        },
        onError: (error) => {
          setStatus('error');
          console.error('onError', error);
        },
        onUpdate: (msg) => {
          setLines((pre) => [...pre, msg]);
          console.log('onUpdate', msg);
        },
       onStream: (controller) => {
          abortController.current = controller;
        }
      },
    );
  const abort = () => {
    abortController?.current?.abort?.();
  }

<Button onClick={abort}/>

useXAgent

ISSUE

1、没有提供终止方法
2、demo模拟的流很简单内容也为简单字符串实际模型返回的是json string需要做解析，目前如果要自己做解析只能自定义request成本较高。

API

继承XRequest 的 onStream和 transformStream

Example Usage

同 XRequest

useXChat

ISSUE

以下三点会直接导致 useXChat 根本不能落地
1、无法自定义params ,导致默认非流式 stream = false.
2、无法终止回答，现在的demo基于自定义request，同时使用API目前不建议，建议删掉demo，新的能力需要请求真实接口，会给出新的demo
3、无法处理模型接口数据，demo都是简单字符串，message也处理的比较死，真实接口为json string，已有的parser 无法处理流式数据同时,也没有真实变更messages导致再次发送的数据和模型入参数据不一致而报错，根本无法使用。

API

新增resolveAbortController透出 AbortController，transformMessage 将模型数据转化成message，也免去用户写 transformStream 的痛苦。

onRequest 扩展用户的传入参数

Example Usage

  const { onRequest, messages } = useXChat({
    agent,
    requestFallback: () => {
      return {
        content: 'Request failed, please try again!',
        role: 'assistant',
      };
    },
    requestPlaceholder: () => {
      return {
        content: 'Please wait...',
        role: 'assistant',
      };
    },
    transformMessage: (info) => {
      const { originMessage, currentMessage, status } = info || {};
      let currentText = '';
      let originText = '';
      if (status === 'loading' && currentMessage.data && !currentMessage.data.includes('DONE')) {
        const message = JSON.parse(currentMessage.data);
        currentText =
          message?.choices?.[0].delta?.reasoning_content === null
            ? ''
            : message?.choices?.[0].delta?.reasoning_content;
      }
      if (originMessage) {
        originText = originMessage.content || '';
      }
      return {
        content: originText + currentText,
        role: 'assistant',
      };
    },
    resolveAbortController: (controller) => {
      abortController.current = controller;
    },
  });

//  onRequest
 onRequest({
     stream: true,
     message: {
        role: 'user',
        content: nextContent,
      },
  });

[petercat-assistant[bot]]

感谢您提供详细的需求和设计方案。您提到的关于 useXAgent，useXChat，和 XRequest 在真实请求场景下对流的支持问题，确实是一个重要的改进方向。以下是您提出的主要问题和建议：

XRequest

• 问题: 缺乏终止请求的方法。
• 建议: 使用 AbortController 来提供终止功能，并在 XRequestCallbacks 中新增 onStream 返回 abortController。

useXAgent

• 问题: 缺乏终止方法，示例过于简单。
• 建议: 继承 XRequest 的 onStream 和 transformStream。

useXChat

• 问题:
  1. 无法自定义参数，默认 stream = false。
  2. 无法终止回答，现有示例不建议使用。
  3. 无法处理复杂的模型接口数据。
• 建议:
  • 透出 AbortController。
  • 提供 transformMessage 方法以简化用户的流数据处理。

这些改进建议将有助于提高这些功能在实际应用中的灵活性和可靠性。我们会将您的建议纳入考虑，并在后续版本中进行评估和实施。

如果您有更多的建议或需要进一步的帮助，请随时告知。

🪧 Tips

For further assistance, please describe your question in the comments and @petercat-assistant to start a conversation with me.

[onefeng123]

useXChat 考虑支持多对话吗？现在demo里是单对话。
目前实现对话切换需要通过手动清空消息历史记录。

[onefeng123]

另外 useXAgent不支持传递额外参数 #536
如果 useXChat 考虑支持对话id的话，期望可以让 useXAgent 接收额外参数（现在是通过hack来传递对话id的）。

[kimteayon]

是这样的 useXChat 是单实例，如果你这边调用了多个useXChat 数据也是隔离的，如果你的数据串了说明你用了单一实例去管理了多会话目前不建议这样用会引起不必要的数据处理，做复杂的数据管理并不是我们的初衷。如果要做多会话， 需要配合数据管理工具来实现比如 valtio。

如果你这边使用同一个useXAgent和useXChat 做所有会话的管理，那需要你这边对数据进行处理
1、可以利用数据管理工具 比如 valtio 将对话存储为Map(sessionId => messages)
2、切换用户时将旧的useXChat清理空、并将还在stream的会话打断、同时从valtio获取历史数据放入messages;

最后附上数据应该的样子，这样看来即使id一样也没有关系

const messages = new Map([
['session1',[{id:1,messages:[]},{id:2,messages:[]}],
['session2',[{id:1,messages:[]},{id:2,messages:[]}]
])

[kimteayon]

另外实际 useXAgent 和 XRequest 是可以随便传的 可以自定义Input类型

[onefeng123]

另外实际 useXAgent 和 XRequest 是可以随便传的 可以自定义Input类型

还没注意到这个api，下次重构时试试

[onefeng123]

是这样的 useXChat 是单实例。。。

是的，现在在外部管理对话的消息，每次切换对话时调用 setMessages

[kimteayon]

我大概推导了一下单实例需要解决的问题
1、停止会话 这个RFC已经可以支持
2、后续新增id前缀的配置 可以提供流中的数据归属标识

[kimteayon]

@onefeng123

[onefeng123]

👍