Ant Design X Runtime - 建设讨论

[YumoImer]

🎯 要做什么？

• Ant Design System For X - 设计交互规范
• UIKits - 帮助开发者搭建 AI 交互界面
  • 原子 - 应对复杂、定制化、创新等 ToC 类应用
  • Chat：究极 📦 方案，应对可模版化、无/轻定制需求，如调试「本地、云端」、Agent 平台等 ToB 类应用
• Client Runtime - 帮助开发者搭建 AI Application
  • Tools - 基础工具设施，如 fetch、stream、adapter等
  • Hooks - 基础 React Hook 设施：useXAgent、useXMemory、useXAction、useXPlan

🧑‍💻 目标用户是谁？

🌟 为重点目标用户：

• 前端攻城 🦁，立身之本。
• 往往 算法、服务端攻城 🦁 有对应的前端攻城 🦁 或纯玩、纯调试。
• 面向未来，或许「懂一点点开发/非研发从业者/AI 好奇者」是我们的第二用户群体？

不仅仅是前端开发者：

• 🌟我是一个前端攻城 🦁：搭建应用（Chat、Platform、创新类）、对接模型、对接服务端
• 我是一个算法攻城 🦁：快速搭建一个本地页面，可视化调试模型
• 我是一个服务端攻城 🦁：快速搭建部署一个页面可以调用 API 即可，更多的是能够对接各种模型
• 🌟我是一个懂一点点开发/非研发从业者/AI 好奇者：搭建一个仅服务于自己的本地模型玩一玩/探索投入生产

🚀 要做成什么样子？

👀 如何去做？

🔎 展开讲讲

关于各个 Tools

• XFetch
  • 核心实现：以标准的 fetch 封装，处理全局异常、请求中间件等逻辑
• XStream
  • 核心实现：将流编解码通用逻辑抽象
• XAdapter
  • 核心实现：适配各个主流模型间的协议差异

关于各个 Runtime Hook

• useXAgent
  • 核心实现：搞定各模型数据 -> X Atom Components 可消费的数据
  • 集成 XFetch、XAdapter等 Tools
• useXMemory
  • 核心实现：搞定聊天记录以二进制流数据进行数据管理
  • 集成 XStream 等 Tools
• useXAction
  • 核心实现：搞定渲染行动、函数调用行动
  • 集成 XFetch、XStream 等 Tools
• useXPlan
  • 核心实现：搞定行动链，以及链状态的维护

API

XFetch

interface XFetchResult extends Response {
 // ...
}

interface XFetchOptions extends RequestInit {
  fetch?: typeof fetch;
 // 请求拦截
  onRequest?: (request: Request) => Promise<Request>;
 // 返回拦截
  onResponse?: (response: Response) => Promise<XFetchResult>;
}

type XFetch = (baseURL: string, options: XFetchOptions) => Promise<XFetchResult>;

XStream

interface XStreamResult {
  // ...
}

interface XStreamOptions {
 reader?: ReadableStreamDefaultReader<Uint8Array>;
}

type XStream = (options: XStreamOptions) => AsyncGenerator<XStreamResult>;

XAdapter

interface XAdapterOptions {
  organization?: string;
 model?: string;
}

interface XAdapterResult {
 // 下行适配器
  in: () => any;
 // 上行适配器
 out: () => any;
}

type XAdapter = (options: XAdapterOptions) => XAdapterResult;

useXAgent

import type { XAdapterOptions, XFetchOptions, XStreamOptions } from '@ant-design/x';

interface XAgent {
  id?: string;
  name?: string;
}

interface UseXAgentOptions extends XAgent {
 baseURL?: string;
 organization?: XAdapterOptions['organization'];
 model?: XAdapterOptions['model'];
 fetch?: XFetchOptions;
 stream?: XStreamOptions;
}

type UseXAgentResult = [
 XAgent,
  {
  chat: (options: any) => Promise<any>;
  // ...operations
  },
]

type UseXAgent = (options: UseXAgentOptions) => UseXAgentResult;

useXMemory

import type { XStreamResult, BubbleProps, XStreamOptions } from '@ant-design/x';

interface XMemory {
  id?: string;
  data?: XStreamResult[];
}

interface UseXMemoryOptions extends XMemory {
  stream?: XStreamOptions;
}

type UseXMemoryResult = [
  XMemory,
  {
  read: () => BubbleProps[];
  storage: (items: BubbleProps[]) => void;
  // ...operations
 },
];

type UseXMemory = (options: UseXMemoryOptions) => UseXMemoryResult;

useXAction

import type { XFetchOptions, XStreamOptions } from '@ant-design/x';

enum ACTION_STATUS {
  PENDING = 'pending',
  SUCCESS = 'success',
  ERROR = 'error',
}

interface XAction {
  id?: string;
 type?: 'render' | 'function';
 status?: `${ACTION_STATUS}`;
}

interface UseXActionOptions extends XAction {
 fetch?: XFetchOptions;
 stream?: XStreamOptions;
}

interface UseXActionOperations {
 run: () => any;
 // ...operations
}

type UseXActionResult = [
  XAction,
  UseXActionOperations,
];

type UseXAction = (options: UseXActionOptions) => UseXActionResult;

useXPlan

import type { UseXActionOperations } from '@ant-design/x';

enum PLAN_STATUS {
  PENDING = 'pending',
  SUCCESS = 'success',
  ERROR = 'error',
}

interface XPlan {
  id?: string;
 operations?: UseXActionOperations[];
 status?: `${PLAN_STATUS}`;
 current?: string;
}

interface UseXPlanOptions extends XPlan {
 // ...
}

type UseXPlanResult = [
  XPlan,
  {
  run: () => any;
  cancel: () => any;
  // ...operations
 },
];

type UseXPlan = (options: UseXPlanOptions) => UseXPlanResult;

🏎️ 如何使用

开箱即用

究极 📦 方案，应对可模版化、无/轻定制需求，如调试「本地、云端」、Agent 平台等 ToB 类应用：

import React from 'react';
import { Chat } from '@ant-design/x';

const App = (props) => {
  const xAdapterOptions = {
    organization: 'openai',
    model: 'gpt-3.5-turbo',
  };

  const xFetchOptions = {
    onRequest: async () => {
      // ...
    },
    onResponse: async () => {
      // ...
    },
  };

  return (
  <Chat
   baseURL="https://api.myagent.com"
   fetch={xFetchOptions}
   {...xAdapterOptions}
  />
 );
};

配合原子组件使用

应对复杂、定制化、创新等 ToC 类应用

import React from 'react';
import {
  // atom components
  Bubble,
  Conversations,
  Sender,
  // runtime
  useXAgent,
  useXMemory,
} from '@ant-design/x';
import { Divider, Flex } from 'antd';

const xAdapterOptions = {
  organization: 'openai',
  model: 'gpt-3.5-turbo',
};

const App = (props) => {

  const xFetchOptions = {
    onRequest: async () => {
      // ... 如果需要
    },
    onResponse: async () => {
      // ... 如果需要
    },
  };

  const [value, setValue] = React.useState('');

  const [agent, agentOperations] = useXAgent({
    // API 服务地址
    baseURL: 'https://api.myagent.com',
    // 请求配置
    fetch: xFetchOptions,
    // 适配器配置
    ...xAdapterOptions,
  });

  const [memory, memoryOperations] = useXMemory({
    // 流处理配置
    stream: agent.stream,
    // I：将模型协议数据 -> adapter.in -> bubble 协议数据
    onRead: agentOperations.in,
    // O：将 bubble 协议数据 -> adapter.out -> 模型协议数据
    onStorage: agentOperations.out,
  });

  const convItems = [agent];

  const onSubmit = async (val: string) => {
    const bubbleInfo = {
      role: 'user', content: val,
    };

    // 内部会处理 adapter.out
    await agentOperations.chat([bubbleInfo]);

    // 已经配置了 useXMemory.options.onStorage
    memoryOperations.storage(bubbleInfo);
  };

  // 已经配置了 useXMemory.options.onRead
  const bubbleListItems = memoryOperations.read();

  return (
    <Flex>
      <Conversations items={convItems} />
      <Divider type="vertical" />
      <Flex vertical>
        <Bubble.List style={{ flex: 1 }} items={bubbleListItems} />
        <Sender
          value={value}
          onChange={(nextVal) => {
            setValue(nextVal);
          }}
          onSubmit={onSubmit}
        />
      </Flex>
    </Flex>
  );
};

多项建议

import React from 'react';
import { Bubble, Prompts, Sender, useXAgent } from '@ant-design/x';

import { SmileOutlined, UserOutlined } from '@ant-design/icons';
import { Flex, type GetProp } from 'antd';

const sleep = () => new Promise((resolve) => setTimeout(resolve, 1000));

const roles: GetProp<typeof Bubble.List, 'roles'> = {
  user: {
    placement: 'end',
    avatar: { icon: <UserOutlined />, style: { background: '#87d068' } },
  },
  ai: {
    placement: 'start',
    avatar: { icon: <UserOutlined />, style: { background: '#fde3cf' } },
    typing: true,
  },
  suggestion: {
    placement: 'start',
    avatar: { icon: <UserOutlined />, style: { visibility: 'hidden' } },
    variant: 'borderless',
    messageRender: (content) => (
      <Prompts
        vertical
        items={(content as any as string[]).map((text) => ({
          key: text,
          icon: <SmileOutlined style={{ color: '#FAAD14' }} />,
          description: text,
        }))}
      />
    ),
  },
};

const xAdapterOptions = {
  organization: 'openai',
  model: 'gpt-3.5-turbo',
};

const App = (props) => {

  const [value, setValue] = React.useState('');

  const [agent, agentOperations] = useXAgent({
    // API 服务地址
    baseURL: 'https://api.myagent.com',
    // 适配器配置
    ...xAdapterOptions,
  });

  const [memory, memoryOperations] = useXMemory({
    // 流处理配置
    stream: agent.stream,
    // I：将模型协议数据 -> adapter.in -> bubble 协议数据
    onRead: agentOperations.in,
    // O：将 bubble 协议数据 -> adapter.out -> 模型协议数据
    onStorage: agentOperations.out,
  });

  const convItems = [agent];

  const onSubmit = async (val: string) => {
    const bubbleInfo = {
      role: 'user', content: val,
    };

    // 将用户发送的消息，更新至 memory
    memoryOperations.storage(bubbleInfo);

    // 请求服务后，大模型回答的结果
    const {
      success,
      // mock 数据
      items = [
        {
          role: 'ai',
          content: `Do you want?`,
        },
        {
          role: 'suggestion',
          content: [`Look at: ${val}`, `Search: ${val}`, `Try: ${val}`],
        },
      ],
    } = await agentOperations.chat([bubbleInfo]);

    // 将模型返回的消息，更新至 memory，items 的类型BubbleList.items
    success && memoryOperations.storage(items);
  };

  // 已经配置了 useXMemory.options.onRead
  const bubbleListItems = memoryOperations.read();

  const loading = agent.fetch.status === 'pending';

  return (
    <Flex>
      <Conversations items={convItems} />
      <Divider type="vertical" />
      <Flex vertical>
        <Bubble.List
          roles={roles}
          items={
            [
              ...bubbleListItems,
              // 请求中，设置临时 loading 消息
              loading && {
                role: 'ai',
                key: 'pending',
                loading: true,
              },
            ]
          }
        />
        <Sender
          value={value}
          loading={loading}
          onChange={(nextVal) => {
            setValue(nextVal);
          }}
          onSubmit={onSubmit}
        />
      </Flex>
    </Flex>
  );
};

📚 相关文献

https://lilianweng.github.io/posts/2023-06-23-agent/

[ONLY-yours]

感觉是不是有些部分是langchain的范畴

[YumoImer]

我的想法是：
整个 Runtime 的设计出发点是运行时，在运行时我们的开发者会涉及到要处理流式消息、上下文管理、渲染等等。

langchain 的话之前了解的有 Node 环境版本、Python 环境版本。感觉和我们这个不冲突。

[zombieJ]

感觉会略重，我非常认同 @ONLY-yours 的这个观点 #34 (comment) :

他们只是想让自己看起来，在调用 ai

我觉得最适合的切入点是提供 session level 的状态管理 hooks，其他的东西让业务自己来实现（主要是 API 大家都不一样，做 proxy 模式又多绕一层）

[YumoImer]

我也认同这个观点，不过感觉时代会淘汰这些 Fake AI😄

晚点我写个上述设计的伪代码使用示例

[YumoImer]

按我目前设想的，更新了 Basic Use。

[afc163]

建议能直接对接 openai sdk，让开发者开箱即用。

[YumoImer]

好的，我计划使用 'useXAgent' 来支持，直接传入openai 实例，明天就这部分我出个伪代码示例。

[YumoImer]

提议👻
API 设计或字段命名 Follow : https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md

[zombieJ]

看起来约定的东西比较多，如果是这个支小宝的例子，流程应该是什么样子的？

https://usexagent.x-73x.pages.dev/components/use-x-agent-cn#components-use-x-agent-demo-suggestions

[YumoImer]

多项建议

已更新～

[afc163]

应该能基于这套东西直接做一个 https://github.com/langchain-ai/weblangchain 出来。

[zombieJ]

useXChat:

• messages: 带有所有的对话信息（包含 role、status 大一统的 BubbleConfig 超集）

const { chat } = useXChat(agent, {
  defaultMessages: `WelcomedInfo(Bubble[role: 'welcome'])`,
  requestPlaceholder,
  requestFailed,
});

chat(message);

useXAgent:

• baseURL: openAI or other qwen
• agent.requesting（加载状态）

// Open AI，提供一些预设的协议来支持
const openAIAgent = useXAgent({
  baseURL,
  key,
  model: 'gpt-3.5-turbo', // Trigger
});

const sockInstance = setupSocket();

// Customize without streaming
const customAIAgent = useXAgent({
  request: (msg, info) => async {
    const res = await fetch('/xxxxx', { msg, otherMsgs: info.messages }); // Or sock.send
    return await res.json(); // 可以前端转化成 Message Gernic
  },
});

// Customize with streaming
const customStreamingAIAgent = useXAgent({
  request: (msg, info, onSuccess, onError, onUpdate) => {
    // 自行处理三态逻辑，以 suc or err 为终结
  }, // 背后是会转成一个 Updater 交给 useXChat 来处理的。
});

// Updater: 一种实现可以支持三态
* suc => insertSucBubble
* fail => inserErrBubble
* info => updateBubbleOrInsertIfNotExist

MessageGeneric

<Message = string>

// 如果是富态交互卡片类型
type MessageCustom = {
  type: 'string' | 'map',
  content: 'string' | MapJSON
};

BubbleList => role['ai' | 'map']

map => renderMap

[mashupeng1]

我是前端菜鸟，但是很注重新知识的学习。有个困惑useXAgent搭配Sender实现流式对话的时候，如果我有一个AI agent的后端，可以调用我自己的后端么？

[YumoImer]

可以，useXAgent 的用途就是和模型服务进行对接的，可以像这样使用：

import { useXAgent } from '@ant-design/x';

/**
 * 🔔 Please replace the BASE_URL, PATH, MODEL, API_KEY with your own values.
 */
const BASE_URL = 'https://your.agent.server';
const PATH = '/your-path';
const MODEL = 'gpt-3.5-turbo';
/** 🔥🔥 Its dangerously! */
// const API_KEY = '';

const Demo = () => {

  const [agent] = useXAgent<YourMessageType>({
    baseURL: BASE_URL + PATH,
    model: MODEL,
    // dangerouslyApiKey: API_KEY,
  });

 // ... Render Sender
}