XRequest

XRequest(baseURL, options) 返回带 run、abort、manual 的实例。baseURL 必须是非空字符串。

交给 Provider 时 manual 必须为 true。回调写在 options.callbacks：onUpdate、onSuccess、onError。run(params) 把这次参数和 options.params 合并后发出去。

响应按 content-type 分流：text/event-stream 走 SSE，application/json 走 JSON。其它类型抛出不支持的 content-type。还可以传 timeout、streamTimeout、middlewares、transformStream 和自定义 fetch。

基础使用

Request Log

Chunks0

Last

基础使用

按钮触发一次请求。fetch 被换成本地 SSE，页面不会访问外网。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXRequestBasicV2' });

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Descriptions, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const BASE_URL = 'https://mock.local';
const PATH = '/get-user-info';

const status = ref<ThoughtChainItemType['status']>();
const lines = ref<Record<string, string>[]>([]);
const busy = ref(false);

function request() {
  busy.value = true;
  status.value = 'loading';
  lines.value = [];
  XRequest(BASE_URL + PATH, {
    fetch: createMockOpenAIFetch(() => 'Hello from XRequest basic.'),
    params: { stream: true, messages: [{ role: 'user', content: 'ping' }] },
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        busy.value = false;
      },
      onError: () => {
        status.value = 'error';
        busy.value = false;
      },
      onUpdate: (msg) => {
        lines.value = [...lines.value, msg as Record<string, string>];
      },
    },
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Request Log',
    status: status.value,
    icon: status.value === 'loading' ? <LoadingOutlined /> : <TagsOutlined />,
    content: (
      <Descriptions column={1} size="small">
        <Descriptions.Item label="Chunks">{String(lines.value.length)}</Descriptions.Item>
        <Descriptions.Item label="Last">
          <pre style={{ margin: 0, whiteSpace: 'pre-wrap' }}>
            {lines.value.length ? JSON.stringify(lines.value[lines.value.length - 1]) : '-'}
          </pre>
        </Descriptions.Item>
      </Descriptions>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={busy.value} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

自定义入参

Request Log

自定义入参

在 params 里附带 agentId 等自定义字段，仍然走本地 mock。

自定义转换器

transformStream + NDJSON mock，把原始分片原样送进 onUpdate。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXRequestCustomTransformerV2' });

import { computed, ref } from 'vue';
import { TagsOutlined } from '@ant-design/icons-vue';
import { Button, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockNdjsonFetch } from '../../_shared/mock-chat';

const BASE_URL = 'https://mock.local';
const PATH = '/chat';
const ND_JSON_SEPARATOR = '\n';

const ndJsonData = `{data:{"id":"0","choices":[{"index":0,"delta":{"content":"Hello","role":"assistant"}}],"created":1733129200,"model":"gpt-4o"}}
{data:{"id":"1","choices":[{"index":1,"delta":{"content":"world!","role":"assistant"}}],"created":1733129300,"model":"gpt-4o"}}
{data:{"id":"2","choices":[{"index":2,"delta":{"content":"I","role":"assistant"}}],"created":1733129400,"model":"gpt-4o"}}
{data:{"id":"3","choices":[{"index":3,"delta":{"content":"am","role":"assistant"}}],"created":1733129500,"model":"gpt-4o"}}
{data:{"id":"4","choices":[{"index":4,"delta":{"content":"Ant Design X!","role":"assistant"}}],"created":1733129600,"model":"gpt-4o"}}`;

const status = ref<ThoughtChainItemType['status']>();
const lines = ref<string[]>([]);
const busy = ref(false);

function request() {
  busy.value = true;
  status.value = 'loading';
  lines.value = [];
  XRequest(BASE_URL + PATH, {
    params: {
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'hello, who are u?' }],
      stream: true,
      agentId: 111,
    },
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        busy.value = false;
      },
      onError: () => {
        status.value = 'error';
        busy.value = false;
      },
      onUpdate: (msg) => {
        lines.value = [...lines.value, String(msg)];
      },
    },
    transformStream: new TransformStream<string, string>({
      transform(chunk, controller) {
        controller.enqueue(chunk);
      },
    }),
    fetch: createMockNdjsonFetch(ndJsonData.split(ND_JSON_SEPARATOR)),
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Mock Custom Protocol - Log',
    status: status.value,
    icon: <TagsOutlined />,
    content: (
      <pre style={{ overflow: 'auto', margin: 0 }}>
        <code>{lines.value.join(ND_JSON_SEPARATOR)}</code>
      </pre>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={busy.value} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={status.value ? items.value : []} />
  </Flex>
));
</script>

模型接入

Model Request Log

idle

模型接入

手动模式 + 输入框，用 mock OpenAI SSE 模拟模型流式回复，可 Abort。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXRequestModelV2' });

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Flex, Input } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';
import { createMockOpenAIFetch } from '../../_shared/mock-chat';

const MODEL = 'mock-gpt';
const questionText = ref('hello, who are u?');
const status = ref('');
const thoughtChainStatus = ref<ThoughtChainItemType['status']>();
const lines = ref<unknown[]>([]);
const requestHandler = XRequest('https://mock.local/v1/chat/completions', {
  manual: true,
  fetch: createMockOpenAIFetch((text) => `Mock model reply for: ${text || questionText.value}`),
  params: { model: MODEL, stream: true },
  callbacks: {
    onSuccess: () => {
      status.value = 'success';
      thoughtChainStatus.value = 'success';
    },
    onError: (error) => {
      status.value = error.message;
      thoughtChainStatus.value = 'error';
    },
    onUpdate: (msg) => {
      lines.value = [...lines.value, msg];
    },
  },
});

function request() {
  status.value = 'pending';
  thoughtChainStatus.value = 'loading';
  lines.value = [];
  requestHandler.run({
    messages: [{ role: 'user', content: questionText.value }],
    stream: true,
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Model Request Log',
    status: thoughtChainStatus.value,
    icon: status.value === 'pending' ? <LoadingOutlined /> : <TagsOutlined />,
    description: status.value || 'idle',
    content: (
      <pre style={{ margin: 0, whiteSpace: 'pre-wrap', overflow: 'auto', maxHeight: 180 }}>
        {lines.value.map((line) => JSON.stringify(line)).join('\n') || '-'}
      </pre>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={12} align="flex-start" style={{ width: '100%' }}>
    <Input.TextArea
      value={questionText.value}
      autoSize={{ minRows: 2, maxRows: 4 }}
      onUpdate:value={(v: string) => { questionText.value = v; }}
      style={{ width: '100%' }}
    />
    <Flex gap={8}>
      <Button type="primary" disabled={status.value === 'pending'} onClick={request}>
        Run model request
      </Button>
      <Button onClick={() => requestHandler.abort()}>Abort</Button>
    </Flex>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

超时配置

Request Log

request -

Status-

timeout2000ms (mock arrives at 3000ms)

超时配置

timeout: 2000，mock 在 3000ms 才返回，触发 TimeoutError。

<script setup lang="tsx">
defineOptions({ name: 'AXSdkXRequestTimeoutV2' });

import { computed, ref } from 'vue';
import { LoadingOutlined, TagsOutlined } from '@ant-design/icons-vue';
import { Button, Descriptions, Flex } from 'ant-design-vue';
import { ThoughtChain, XRequest, type ThoughtChainItemType } from 'ant-design-x-vue';

const BASE_URL = 'https://mock.local';
const PATH = '/chat';

async function mockFetch() {
  return new Promise<Response>((resolve) => {
    setTimeout(() => {
      resolve(
        new Response('{ "data": "Hi" }', {
          status: 200,
          headers: { 'Content-Type': 'application/json' },
        }),
      );
    }, 3000);
  });
}

const status = ref('');
const thoughtChainStatus = ref<ThoughtChainItemType['status']>();

function request() {
  status.value = 'pending';
  thoughtChainStatus.value = 'loading';
  XRequest(BASE_URL + PATH, {
    timeout: 2000,
    fetch: mockFetch,
    callbacks: {
      onSuccess: () => {
        status.value = 'success';
        thoughtChainStatus.value = 'success';
      },
      onError: (error) => {
        status.value = error.message === 'TimeoutError' ? 'TimeoutError' : error.message;
        thoughtChainStatus.value = 'error';
      },
    },
  });
}

const items = computed(() => [
  {
    key: 'log',
    title: 'Request Log',
    status: thoughtChainStatus.value,
    icon: status.value === 'pending' ? <LoadingOutlined /> : <TagsOutlined />,
    description: `request ${status.value || '-'}`,
    content: (
      <Descriptions column={1} size="small">
        <Descriptions.Item label="Status">{status.value || '-'}</Descriptions.Item>
        <Descriptions.Item label="timeout">2000ms (mock arrives at 3000ms)</Descriptions.Item>
      </Descriptions>
    ),
  },
]);

defineRender(() => (
  <Flex vertical gap={16} align="flex-start">
    <Button type="primary" disabled={status.value === 'pending'} onClick={request}>
      Request - {BASE_URL}{PATH}
    </Button>
    <ThoughtChain items={items.value} />
  </Flex>
));
</script>

API

XRequestFunction

type XRequestFunction<Input = AnyObject, Output = SSEOutput> = (
  baseURL: string,
  options?: XRequestOptions<Input, Output>,
) => XRequestClass<Input, Output>;

属性	说明	类型	默认值	版本
baseURL	API 地址	string	-	-
options	请求配置	XRequestOptions<Input, Output>	-	-

XRequestOptions

属性	说明	类型	默认值	版本
callbacks	请求回调	XRequestCallbacks<Output>	-	-
params	请求参数	Input	-	-
headers	额外请求头	Record<string, string>	-	-
timeout	请求超时（毫秒）	number	-	-
streamTimeout	流式数据超时（毫秒）	number	-	-
fetch	自定义 fetch	(baseURL, options) => Promise<Response>	-	-
middlewares	请求前后中间件	XFetchMiddlewares<Input, Output>	-	-
transformStream	流处理器	XStreamOptions<Output>['transformStream'] \| ((baseURL: string, responseHeaders: Headers) => XStreamOptions<Output>['transformStream'])	-	-
manual	是否手动发请求；为 `true` 时需调用 `run`	boolean	false	-

XRequestCallbacks

属性	说明	类型	默认值	版本
onSuccess	成功回调	(chunks: Output[], responseHeaders: Headers) => void	-	-
onError	错误回调	(error: Error) => void	-	-
onUpdate	分片更新回调	(chunk: Output, responseHeaders: Headers) => void	-	-

XRequestClass

属性	说明	类型	默认值	版本
abort	取消请求	() => void	-	-
run	手动执行请求（`manual=true` 时生效）	(params?: Input) => void	-	-
isRequesting	是否正在请求	boolean	-	-
manual	是否手动模式	boolean	-	-

setXRequestGlobalOptions

type setXRequestGlobalOptions<Input, Output> = (
  options: XRequestGlobalOptions<Input, Output>,
) => void;

XRequestGlobalOptions

type XRequestGlobalOptions<Input, Output> = Pick<
  XRequestOptions<Input, Output>,
  'headers' | 'timeout' | 'streamTimeout' | 'middlewares' | 'fetch' | 'transformStream' | 'manual'
>;

XFetchMiddlewares

interface XFetchMiddlewares<Input, Output> {
  onRequest?: (
    ...args: [Parameters<typeof fetch>[0], XRequestOptions<Input, Output>]
  ) => Promise<[Parameters<typeof fetch>[0], XRequestOptions<Input, Output>]>;
  onResponse?: (response: Response) => Promise<Response>;
}

1.x 的 new XRequest({ baseURL, model, dangerouslyApiKey }).create 现在叫 XRequestLegacy，文档在 XRequest 请求。

XRequest ​

基础使用 ​

自定义入参 ​

自定义转换器 ​

模型接入 ​

超时配置 ​

API ​

XRequestFunction ​

XRequestOptions ​

XRequestCallbacks ​

XRequestClass ​

setXRequestGlobalOptions ​

XRequestGlobalOptions ​

XFetchMiddlewares ​

XRequest

基础使用

自定义入参

自定义转换器

模型接入

超时配置

API

XRequestFunction

XRequestOptions

XRequestCallbacks

XRequestClass

setXRequestGlobalOptions

XRequestGlobalOptions

XFetchMiddlewares