메뉴
Focus on implementing custom Chat Provider, helping to adapt any streaming interface to Ant Design X standard format
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/ant-design/x --skill x-chat-provider명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | x-chat-provider |
| version | 2.9.0 |
| description | Focus on implementing custom Chat Provider, helping to adapt any streaming interface to Ant Design X standard format |
This skill focuses on solving one problem: How to quickly adapt your streaming interface to Ant Design X's Chat Provider.
Not involved: useXChat usage tutorial (that's another skill).
| Layer | Package Name | Core Purpose |
|---|
| UI Layer | @ant-design/x | React UI component library |
| Logic Layer | @ant-design/x-sdk | Development toolkit |
| Render Layer | @ant-design/x-markdown | Markdown renderer |
// ✅ Correct import examples
import { Bubble } from '@ant-design/x';
import { AbstractChatProvider, OpenAIChatProvider } from '@ant-design/x-sdk';
import XRequest from '@ant-design/x-sdk';
graph TD
A[Start] --> B{Use standard OpenAI/DeepSeek API?}
B -->|Yes| C[Use built-in Provider]
B -->|No| D{Raw data format as message?}
D -->|Yes| E[Use DefaultChatProvider]
D -->|No| F[Custom Provider]
C --> G[OpenAIChatProvider / DeepSeekChatProvider]
E --> H[Pass-through, no conversion needed]
F --> I[Four-step custom Provider]
| Provider Type | Applicable Scenario | Import |
|---|---|---|
| OpenAIChatProvider | Standard OpenAI API format | import { OpenAIChatProvider } from '@ant-design/x-sdk' |
| DeepSeekChatProvider | Standard DeepSeek API format | import { DeepSeekChatProvider } from '@ant-design/x-sdk' |
| DefaultChatProvider | Pass-through raw response, no format conversion | import { DefaultChatProvider } from '@ant-design/x-sdk' |
⚠️ Export names are
OpenAIChatProvider/DeepSeekChatProvider/DefaultChatProvider, watch spelling
DefaultChatProvider passes through raw response data without any conversion. Suitable for:
Bubble.List's contentRender to render messagesimport { DefaultChatProvider, XRequest } from '@ant-design/x-sdk';
interface ChatInput {
query: string;
stream?: boolean;
}
interface ChatOutput {
choices: Array<{ message: { content: string; role: string } }>;
}
// DefaultChatProvider generic: <ChatMessage, Input, Output>
// ChatMessage is your Output type (passed through directly)
const provider = new DefaultChatProvider<ChatOutput | ChatInput, ChatInput, ChatOutput>({
request: XRequest('https://your-api.com/chat', {
manual: true,
params: { stream: false },
}),
});
// Render using contentRender in Bubble.List's role config
// role={{ assistant: { contentRender(content) { return content?.choices?.[0]?.message?.content } } }}
⚠️ When using
DefaultChatProvider,ChatMessageis typically yourOutputtype or a union type; rendering requirescontentRender
| Information Type | Example Value |
|---|---|
| Interface URL | https://your-api.com/chat |
| Request Method | JSON, POST |
| Response Format | Server-Sent Events |
| Auth Method | Bearer Token |
// MyChatProvider.ts
import { AbstractChatProvider } from '@ant-design/x-sdk';
import type { TransformMessage } from '@ant-design/x-sdk';
import type { XRequestOptions } from '@ant-design/x-sdk';
interface MyInput {
query: string;
model?: string;
stream?: boolean;
}
interface MyOutput {
content: string;
finish_reason?: string;
}
interface MyMessage {
content: string;
role: 'user' | 'assistant';
}
export class MyChatProvider extends AbstractChatProvider<MyMessage, MyInput, MyOutput> {
// Parameter conversion: merge onRequest params + XRequest default params
// options comes from XRequest(url, options), can access options.params etc.
transformParams(
requestParams: Partial<MyInput>,
options: XRequestOptions<MyInput, MyOutput, MyMessage>,
): MyInput {
return {
...(options?.params || {}),
query: requestParams.query || '',
model: 'gpt-3.5-turbo',
stream: true,
};
}
// Local message: convert onRequest params to the user-side display message (can return array)
transformLocalMessage(requestParams: Partial<MyInput>): MyMessage {
return {
content: requestParams.query || '',
role: 'user',
};
}
// Response conversion:
// info.originMessage: previous content of this message (for stream accumulation)
// info.chunk: current streaming chunk
// info.chunks: all received chunks (used in onSuccess)
// info.status: current status
// ⚠️ Return only MyMessage type; do NOT add a status field
transformMessage(info: TransformMessage<MyMessage, MyOutput>): MyMessage {
const { originMessage, chunk } = info;
if (!chunk?.content || chunk.content === '[DONE]') {
return { ...(originMessage || { content: '', role: 'assistant' }) };
}
return {
content: `${originMessage?.content || ''}${chunk.content}`,
role: 'assistant',
};
}
}
| Check Item | Description |
|---|---|
| Only 3 methods | transformParams, transformLocalMessage, transformMessage |
| transformParams signature | Must include second parameter options: XRequestOptions<...> |
| No status in return | transformMessage return value has no status field |
| No request method | Confirm no request method implemented |
| Type check passes | tsc --noEmit no errors |
import { MyChatProvider } from './MyChatProvider';
import XRequest from '@ant-design/x-sdk';
// ⚠️ Must pass manual: true, otherwise AbstractChatProvider constructor will throw
const provider = new MyChatProvider({
request: XRequest('https://your-api.com/chat', {
manual: true,
headers: {
Authorization: 'Bearer your-token',
'Content-Type': 'application/json',
},
params: {
model: 'gpt-3.5-turbo',
stream: true,
},
}),
});
export { provider };
Key types exported from @ant-design/x-sdk:
import type {
// OpenAI standard message format
XModelMessage, // { role: string; content: string | { text: string; type: string } }
XModelParams, // Full OpenAI request params type (model, messages, stream, temperature, etc.)
XModelResponse, // Full OpenAI response type (choices, usage, etc.)
// SSE stream field types
SSEFields, // 'data' | 'event' | 'id' | 'retry'
SSEOutput, // Partial<Record<SSEFields, any>>
// Provider related
TransformMessage, // { originMessage, chunk, chunks, status, responseHeaders }
// XRequest related
XRequestOptions, // Full request config
XRequestCallbacks, // { onUpdate, onSuccess, onError }
// Message related
MessageInfo, // { id, message, status, extraInfo }
} from '@ant-design/x-sdk';
// XModelMessage is the standard OpenAI message format
// Used for OpenAIChatProvider / DeepSeekChatProvider ChatMessage generic
const userMessage: XModelMessage = { role: 'user', content: 'Hello' };
const systemMessage: XModelMessage = { role: 'system', content: 'You are an assistant' };
const developerMessage: XModelMessage = { role: 'developer', content: 'System prompt' };
// SSEOutput is the type for raw SSE stream data
// { data?: string; event?: string; id?: string; retry?: number }
// DeepSeekChatProvider uses Partial<Record<SSEFields, XModelResponse>>
import { DeepSeekChatProvider, XRequest } from '@ant-design/x-sdk';
import type { SSEFields, XModelParams, XModelResponse } from '@ant-design/x-sdk';
const provider = new DeepSeekChatProvider({
request: XRequest<XModelParams, Partial<Record<SSEFields, XModelResponse>>>(
'https://api.deepseek.com/v1/chat/completions',
{
manual: true,
params: { model: 'deepseek-chat', stream: true },
},
),
});
callbacks allows monitoring request events at the Provider level. The third parameter in callbacks is the MessageInfo processed by transformMessage:
const provider = new OpenAIChatProvider({
request: XRequest<XModelParams, XModelResponse, XModelMessage>(BASE_URL, {
manual: true,
callbacks: {
// onUpdate: triggered on each streaming chunk arrival
// chunk: current chunk; responseHeaders: response headers; message: current MessageInfo
onUpdate: (chunk, responseHeaders, message) => {
console.log('Stream update:', message?.message?.content);
},
// onSuccess: triggered when all chunks are received
// chunks: all chunks array; message: final MessageInfo
onSuccess: (chunks, responseHeaders, message) => {
console.log('Request complete:', message?.message?.content);
// Good place for analytics, logging, etc.
},
// onError: triggered on request failure (including AbortError)
// error: error object; errorInfo: extra error info; message: MessageInfo at failure
onError: (error, errorInfo, responseHeaders, message) => {
console.error('Request failed:', error.message);
},
},
params: { model: 'gpt-4o', stream: true },
}),
});
⚠️
callbacksanduseXChat'srequestFallbackdo not conflict — both execute.callbacksis better for logging/reporting;requestFallbackcontrols UI display.
const request = XRequest('https://your-api.com/chat', {
manual: true,
// Retry interval after failure (ms)
retryInterval: 3000,
// Max retry count (unlimited if not set)
retryTimes: 3,
// onError can also return a number to dynamically set retry interval
callbacks: {
onError: (error) => {
if (error.name === 'AbortError') return; // Don't retry on user cancel
return 5000; // Return number = retry after 5s (higher priority than retryInterval)
},
},
});
Use when the server returns a non-standard SSE stream format:
const request = XRequest('https://your-api.com/chat', {
manual: true,
// Fixed TransformStream
transformStream: new TransformStream({
transform(chunk, controller) {
controller.enqueue(JSON.parse(chunk));
},
}),
// Or decide dynamically based on URL and response headers
transformStream: (baseURL, responseHeaders) => {
if (responseHeaders.get('x-stream-type') === 'ndjson') {
return new TransformStream({/* ... */});
}
return undefined; // Use default SSE parsing
},
});
📖 Complete Examples: EXAMPLES.md
| Scenario Type | Difficulty | Description |
|---|---|---|
| Standard OpenAI | 🟢 | Use built-in OpenAIChatProvider directly |
| Standard DeepSeek | 🟢 | Use built-in DeepSeekChatProvider directly |
| Pass-through raw data | 🟢 | Use DefaultChatProvider |
| Private SSE API | 🟡 | Four-step custom Provider |
| Multi-field response | 🟡 | Custom Provider + complex ChatMessage |
| Non-SSE stream | 🔴 | Custom Provider + transformStream |
// ❌ Serious error
class MyProvider extends AbstractChatProvider {
async request(params: any) {
/* Forbidden! */
}
}
// ✅ Only correct approach: implement only the three conversion methods
class MyProvider extends AbstractChatProvider {
transformParams(params, options) {
/* ... */
}
transformLocalMessage(params) {
/* ... */
}
transformMessage(info) {
/* ... */
}
}
// ❌ Wrong
transformMessage(info) {
return { content: '...', status: 'error' }; // ❌ status is managed by the framework
}
// ✅ Correct
transformMessage(info) {
return { content: '...' }; // ✅
}
// ✅ In React components, use useState to ensure only created once
const [provider] = React.useState(
new MyChatProvider({
request: XRequest(URL, { manual: true }),
}),
);
// ❌ Don't create directly in render function (creates new instance on every render)
// const provider = new MyChatProvider(...); // inside component body causes issues
Before creating Provider:
After completion:
useState in React componenttsc --noEmit)tsc --noEmit to ensure no type errors