完善文档页文本向量与重排序调用支持
This commit is contained in:
@@ -1,33 +1,52 @@
|
||||
import { useMemo, type FormEvent } from 'react';
|
||||
import type { GatewayTask } from '@easyai-ai-gateway/contracts';
|
||||
import { BookOpen, Play, Search, Send } from 'lucide-react';
|
||||
import { useEffect, useMemo, type FormEvent } from 'react';
|
||||
import type { GatewayApiKey, GatewayTask } from '@easyai-ai-gateway/contracts';
|
||||
import { BookOpen, KeyRound, Play, Search, Send } from 'lucide-react';
|
||||
import { Badge, Button, Select, Textarea } from '../components/ui';
|
||||
import type { ApiDocSection, LoadState, TaskForm } from '../types';
|
||||
import type { ApiDocSection, LoadState, TaskForm, TaskKind } from '../types';
|
||||
import { ApiKeySelect, apiKeyNoticeText, resolveSelectedApiKeyId } from './playground-shared';
|
||||
|
||||
const docs: Array<{ key: ApiDocSection; group: string; method: string; path: string; title: string }> = [
|
||||
{ key: 'chat', group: '聊天(Chat)', method: 'POST', path: '/v1/chat/completions', title: 'Chat(聊天)' },
|
||||
{ key: 'imageGeneration', group: '图片', method: 'POST', path: '/v1/images/generations', title: '创建图片' },
|
||||
{ key: 'imageEdit', group: '图片', method: 'POST', path: '/v1/images/edits', title: '编辑图片' },
|
||||
{ key: 'pricing', group: '计费', method: 'POST', path: '/api/v1/pricing/estimate', title: '价格预估' },
|
||||
{ key: 'files', group: '文件', method: 'POST', path: '/v1/files/upload', title: '上传文件' },
|
||||
interface ApiDocItem {
|
||||
group: string;
|
||||
key: ApiDocSection;
|
||||
kind?: TaskKind;
|
||||
lead: string;
|
||||
method: string;
|
||||
path: string;
|
||||
title: string;
|
||||
}
|
||||
|
||||
const docs: ApiDocItem[] = [
|
||||
{ key: 'chat', group: '文本', kind: 'chat.completions', method: 'POST', path: '/v1/chat/completions', title: 'Chat Completions', lead: 'OpenAI 兼容的对话接口，支持本地 API Key 授权、simulation 测试和非流式/流式响应。' },
|
||||
{ key: 'embeddings', group: '文本', kind: 'embeddings', method: 'POST', path: '/v1/embeddings', title: '文本向量 Embeddings', lead: 'OpenAI 兼容的文本向量接口，可直接用 input 数组或字符串生成 embedding，API Key 需要 embedding 权限。' },
|
||||
{ key: 'reranks', group: '文本', kind: 'reranks', method: 'POST', path: '/v1/reranks', title: '文本重排序 Reranks', lead: 'OpenAI 风格的重排序接口，传入 query 和 documents 后返回 relevance_score，API Key 需要 rerank 权限。' },
|
||||
{ key: 'imageGeneration', group: '图片', kind: 'images.generations', method: 'POST', path: '/v1/images/generations', title: '创建图片', lead: 'OpenAI 兼容的图片生成接口，支持 prompt、size、quality 和 simulation 测试。' },
|
||||
{ key: 'imageEdit', group: '图片', kind: 'images.edits', method: 'POST', path: '/v1/images/edits', title: '编辑图片', lead: 'OpenAI 兼容的图片编辑接口，支持 image、mask、prompt 和 simulation 测试。' },
|
||||
{ key: 'pricing', group: '计费', method: 'POST', path: '/api/v1/pricing/estimate', title: '价格预估', lead: '按请求体估算输入输出 token、模型倍率和折扣后的预估费用。' },
|
||||
{ key: 'files', group: '文件', method: 'POST', path: '/v1/files/upload', title: '上传文件', lead: '上传在线测试所需的图片、音频或视频资源，后续请求可复用返回的文件 URL。' },
|
||||
];
|
||||
|
||||
const guideItems = ['获取 Base URL 和 API Key', '通知设置-WebHook 参数介绍', '错误码', '测试模式'];
|
||||
|
||||
const taskKindOptions = [
|
||||
['chat.completions', 'Chat'],
|
||||
['embeddings', '文本向量'],
|
||||
['reranks', '重排序'],
|
||||
['images.generations', '生图'],
|
||||
['images.edits', '图像编辑'],
|
||||
] as const;
|
||||
|
||||
export function ApiDocsPage(props: {
|
||||
activeDocSection: ApiDocSection;
|
||||
apiKeySecret: string;
|
||||
apiKeySecretsById: Record<string, string>;
|
||||
apiKeys: GatewayApiKey[];
|
||||
canRun: boolean;
|
||||
coreMessage: string;
|
||||
coreState: LoadState;
|
||||
selectedApiKeyId: string;
|
||||
taskForm: TaskForm;
|
||||
taskResult: GatewayTask | null;
|
||||
onApiKeyChange: (apiKeyId: string) => void;
|
||||
onCreateApiKey: () => void;
|
||||
onLogin: () => void;
|
||||
onDocSectionChange: (value: ApiDocSection) => void;
|
||||
onSubmitTask: (event: FormEvent<HTMLFormElement>) => void;
|
||||
@@ -35,8 +54,16 @@ export function ApiDocsPage(props: {
|
||||
}) {
|
||||
const current = docs.find((item) => item.key === props.activeDocSection) ?? docs[0];
|
||||
const isFileDoc = current.key === 'files';
|
||||
const apiKeyNotice = apiKeyNoticeText(props.apiKeys, props.apiKeySecretsById);
|
||||
const activeApiKeyId = resolveSelectedApiKeyId(props.apiKeys, props.apiKeySecretsById, props.selectedApiKeyId);
|
||||
const bodyExample = useMemo(() => requestBodyExample(props.taskForm), [props.taskForm]);
|
||||
|
||||
useEffect(() => {
|
||||
if (current.kind && props.taskForm.kind !== current.kind) {
|
||||
props.onTaskFormChange(defaultTaskForKind(current.kind, props.taskForm));
|
||||
}
|
||||
}, [current.kind, props.taskForm.kind]);
|
||||
|
||||
function handleSubmit(event: FormEvent<HTMLFormElement>) {
|
||||
if (!props.canRun) {
|
||||
event.preventDefault();
|
||||
@@ -46,6 +73,21 @@ export function ApiDocsPage(props: {
|
||||
props.onSubmitTask(event);
|
||||
}
|
||||
|
||||
function handleDocClick(item: ApiDocItem) {
|
||||
if (item.kind) {
|
||||
props.onTaskFormChange(defaultTaskForKind(item.kind, props.taskForm));
|
||||
}
|
||||
props.onDocSectionChange(item.key);
|
||||
}
|
||||
|
||||
function handleKindChange(kind: TaskKind) {
|
||||
props.onTaskFormChange(defaultTaskForKind(kind, props.taskForm));
|
||||
const nextSection = docSectionForKind(kind);
|
||||
if (nextSection !== props.activeDocSection) {
|
||||
props.onDocSectionChange(nextSection);
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="apiDocsShell">
|
||||
<aside className="docsSidebar">
|
||||
@@ -66,7 +108,7 @@ export function ApiDocsPage(props: {
|
||||
active: item.key === props.activeDocSection,
|
||||
method: item.method,
|
||||
title: item.title,
|
||||
onClick: () => props.onDocSectionChange(item.key),
|
||||
onClick: () => handleDocClick(item),
|
||||
}))}
|
||||
/>
|
||||
))}
|
||||
@@ -79,9 +121,7 @@ export function ApiDocsPage(props: {
|
||||
<Badge variant="warning">{current.method}</Badge>
|
||||
<code>{current.path}</code>
|
||||
</div>
|
||||
<p className="docsLead">
|
||||
保持与原 integration-platform / OpenAI 兼容接口一致，支持本地 API Key 和 server-main 接入 token。
|
||||
</p>
|
||||
<p className="docsLead">{current.lead}</p>
|
||||
|
||||
<section className="paramCard">
|
||||
<header>
|
||||
@@ -90,7 +130,7 @@ export function ApiDocsPage(props: {
|
||||
</header>
|
||||
<ParamRow name="Content-Type" type="string" required value={isFileDoc ? 'multipart/form-data' : 'application/json'} />
|
||||
<ParamRow name="Accept" type="string" required value="application/json" />
|
||||
<ParamRow name="Authorization" type="string" value="Bearer {{YOUR_API_KEY}}" />
|
||||
<ParamRow name="Authorization" type="string" required value="Bearer {{YOUR_API_KEY}}，支持本地 API Key；管理接口仍使用 JWT。向量需 embedding 权限，重排序需 rerank 权限。" />
|
||||
</section>
|
||||
|
||||
<section className="paramCard">
|
||||
@@ -104,12 +144,9 @@ export function ApiDocsPage(props: {
|
||||
<ParamRow name="source" type="string" value="上传来源标记" />
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<ParamRow name="model" type="string" required value="模型 ID 或别名" />
|
||||
<ParamRow name="messages / prompt" type="array|string" required value="对话消息或图片提示词" />
|
||||
<ParamRow name="simulation" type="boolean" value="测试模式开关" />
|
||||
<ParamRow name="stream" type="boolean" value="对话进度流式返回" />
|
||||
</>
|
||||
bodyParamRows(current.key).map((row) => (
|
||||
<ParamRow key={row.name} {...row} />
|
||||
))
|
||||
)}
|
||||
</section>
|
||||
</main>
|
||||
@@ -127,9 +164,27 @@ export function ApiDocsPage(props: {
|
||||
<Badge variant="warning">POST</Badge>
|
||||
<span>{current.path}</span>
|
||||
</div>
|
||||
<label className="shLabel">
|
||||
API Key
|
||||
<ApiKeySelect
|
||||
apiKeySecretsById={props.apiKeySecretsById}
|
||||
apiKeys={props.apiKeys}
|
||||
selectedApiKeyId={activeApiKeyId}
|
||||
onApiKeyChange={props.onApiKeyChange}
|
||||
/>
|
||||
</label>
|
||||
{apiKeyNotice && (
|
||||
<div className="docsKeyNotice">
|
||||
<span>{apiKeyNotice}</span>
|
||||
<Button type="button" size="sm" variant="secondary" onClick={props.onCreateApiKey}>
|
||||
<KeyRound size={14} />
|
||||
创建 Key
|
||||
</Button>
|
||||
</div>
|
||||
)}
|
||||
<label className="shLabel">
|
||||
能力
|
||||
<Select value={props.taskForm.kind} onChange={(event) => props.onTaskFormChange(defaultTaskForKind(event.target.value as TaskForm['kind'], props.taskForm))}>
|
||||
<Select value={props.taskForm.kind} onChange={(event) => handleKindChange(event.target.value as TaskKind)}>
|
||||
{taskKindOptions.map(([value, label]) => (
|
||||
<option value={value} key={value}>{label}</option>
|
||||
))}
|
||||
@@ -198,16 +253,39 @@ function groupDocs(items: typeof docs) {
|
||||
|
||||
function defaultTaskForKind(kind: TaskForm['kind'], current: TaskForm): TaskForm {
|
||||
if (kind === 'chat.completions') return { ...current, kind, model: 'gpt-4o-mini' };
|
||||
if (kind === 'embeddings') {
|
||||
return {
|
||||
...current,
|
||||
dimensions: current.dimensions ?? 4,
|
||||
kind,
|
||||
model: 'text-embedding-v4',
|
||||
prompt: current.prompt || 'AI Gateway 提供 OpenAI 兼容接口。',
|
||||
};
|
||||
}
|
||||
if (kind === 'reranks') {
|
||||
return {
|
||||
...current,
|
||||
documents: current.documents ?? 'AI Gateway 提供 OpenAI 兼容接口。\n图片生成任务支持异步队列。\n文本向量接口返回 embedding 数组。',
|
||||
kind,
|
||||
model: 'qwen3-rerank',
|
||||
prompt: current.prompt || 'OpenAI 兼容接口',
|
||||
topN: current.topN ?? 2,
|
||||
};
|
||||
}
|
||||
if (kind === 'images.edits') return { ...current, kind, image: current.image ?? 'https://example.com/source.png', mask: current.mask ?? 'https://example.com/mask.png', model: 'gpt-image-1' };
|
||||
return { ...current, kind, model: 'gpt-image-1' };
|
||||
}
|
||||
|
||||
function requestBodyExample(task: TaskForm) {
|
||||
const body = task.kind === 'chat.completions'
|
||||
? { model: task.model, messages: [{ role: 'user', content: task.prompt }], simulation: true, stream: true }
|
||||
: task.kind === 'images.edits'
|
||||
? { model: task.model, prompt: task.prompt, image: task.image, mask: task.mask, simulation: true }
|
||||
: { model: task.model, prompt: task.prompt, quality: 'medium', simulation: true, size: '1024x1024' };
|
||||
? { model: task.model, messages: [{ role: 'user', content: task.prompt }], runMode: 'simulation', simulation: true, stream: false }
|
||||
: task.kind === 'embeddings'
|
||||
? { model: task.model, input: embeddingInputExample(task.prompt), dimensions: task.dimensions ?? 4, runMode: 'simulation', simulation: true }
|
||||
: task.kind === 'reranks'
|
||||
? { model: task.model, query: task.prompt, documents: rerankDocumentsExample(task.documents), top_n: task.topN ?? 2, runMode: 'simulation', simulation: true }
|
||||
: task.kind === 'images.edits'
|
||||
? { model: task.model, prompt: task.prompt, image: task.image, mask: task.mask, runMode: 'simulation', simulation: true }
|
||||
: { model: task.model, prompt: task.prompt, quality: 'medium', runMode: 'simulation', simulation: true, size: '1024x1024' };
|
||||
return JSON.stringify(body, null, 2);
|
||||
}
|
||||
|
||||
@@ -219,15 +297,84 @@ function parseBody(value: string, current: TaskForm): TaskForm {
|
||||
messages?: Array<{ content?: string }>;
|
||||
model?: string;
|
||||
prompt?: string;
|
||||
input?: string | string[];
|
||||
query?: string;
|
||||
documents?: string[];
|
||||
top_n?: number;
|
||||
dimensions?: number;
|
||||
};
|
||||
return {
|
||||
...current,
|
||||
dimensions: numberOrCurrent(body.dimensions, current.dimensions),
|
||||
documents: Array.isArray(body.documents) ? body.documents.join('\n') : current.documents,
|
||||
image: body.image ?? current.image,
|
||||
mask: body.mask ?? current.mask,
|
||||
model: body.model ?? current.model,
|
||||
prompt: body.prompt ?? body.messages?.[0]?.content ?? current.prompt,
|
||||
prompt: body.prompt ?? body.query ?? inputText(body.input) ?? body.messages?.[0]?.content ?? current.prompt,
|
||||
topN: numberOrCurrent(body.top_n, current.topN),
|
||||
};
|
||||
} catch {
|
||||
return current;
|
||||
}
|
||||
}
|
||||
|
||||
function bodyParamRows(section: ApiDocSection) {
|
||||
if (section === 'embeddings') {
|
||||
return [
|
||||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名，例如 text-embedding-v4' },
|
||||
{ name: 'input', type: 'string|array', required: true, value: '需要向量化的文本或文本数组' },
|
||||
{ name: 'dimensions', type: 'number', value: '可选向量维度，需模型支持' },
|
||||
{ name: 'runMode / simulation', type: 'string|boolean', value: '在线测试时使用 simulation，不消耗真实上游额度' },
|
||||
];
|
||||
}
|
||||
if (section === 'reranks') {
|
||||
return [
|
||||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名，例如 qwen3-rerank' },
|
||||
{ name: 'query', type: 'string', required: true, value: '用于相关性排序的查询文本' },
|
||||
{ name: 'documents', type: 'array', required: true, value: '候选文档文本数组，至少 1 条' },
|
||||
{ name: 'top_n', type: 'number', value: '返回前 N 条结果' },
|
||||
{ name: 'runMode / simulation', type: 'string|boolean', value: '在线测试时使用 simulation，不消耗真实上游额度' },
|
||||
];
|
||||
}
|
||||
return [
|
||||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名' },
|
||||
{ name: 'messages / prompt', type: 'array|string', required: true, value: '对话消息或图片提示词' },
|
||||
{ name: 'simulation', type: 'boolean', value: '测试模式开关' },
|
||||
{ name: 'stream', type: 'boolean', value: '对话进度流式返回' },
|
||||
];
|
||||
}
|
||||
|
||||
function docSectionForKind(kind: TaskKind): ApiDocSection {
|
||||
if (kind === 'embeddings') return 'embeddings';
|
||||
if (kind === 'reranks') return 'reranks';
|
||||
if (kind === 'images.generations') return 'imageGeneration';
|
||||
if (kind === 'images.edits') return 'imageEdit';
|
||||
return 'chat';
|
||||
}
|
||||
|
||||
function embeddingInputExample(prompt: string) {
|
||||
const lines = splitLines(prompt);
|
||||
return lines.length > 1 ? lines : (lines[0] ?? prompt);
|
||||
}
|
||||
|
||||
function rerankDocumentsExample(value?: string) {
|
||||
return splitLines(value ?? '').length
|
||||
? splitLines(value ?? '')
|
||||
: ['AI Gateway 提供 OpenAI 兼容接口。', '图片生成任务支持异步队列。'];
|
||||
}
|
||||
|
||||
function splitLines(value: string) {
|
||||
return value
|
||||
.split(/\n+/)
|
||||
.map((item) => item.trim())
|
||||
.filter(Boolean);
|
||||
}
|
||||
|
||||
function inputText(value: string | string[] | undefined) {
|
||||
if (Array.isArray(value)) return value.join('\n');
|
||||
return value;
|
||||
}
|
||||
|
||||
function numberOrCurrent(value: unknown, current?: number) {
|
||||
return typeof value === 'number' && Number.isFinite(value) ? value : current;
|
||||
}
|
||||
|
||||
@@ -252,6 +252,7 @@ function modelTypeMatchesCapability(value: string, capability: string) {
|
||||
function canonicalCapabilityValue(value: string) {
|
||||
const type = value.trim().toLowerCase().replaceAll('-', '_');
|
||||
if (type === 'embedding') return 'text_embedding';
|
||||
if (type === 'rerank' || type === 'reranks') return 'text_rerank';
|
||||
if (type === 'model') return 'model_3d';
|
||||
return type;
|
||||
}
|
||||
@@ -265,6 +266,7 @@ function capabilityValueForTag(tag: string) {
|
||||
推理: 'reasoning',
|
||||
结构化输出: 'structured_output',
|
||||
数字人: 'digital_human',
|
||||
重排序: 'text_rerank',
|
||||
'3D 模型': 'model_3d',
|
||||
'文生 3D': 'text_to_model',
|
||||
'图生 3D': 'image_to_model',
|
||||
|
||||
@@ -49,6 +49,7 @@ export type PlatformModelTypeDefinition = {
|
||||
export const platformModelTypeDefinitions: PlatformModelTypeDefinition[] = [
|
||||
{ key: 'text_generate', label: '文本生成', group: '文本', area: 'text' },
|
||||
{ key: 'text_embedding', label: '文本向量', group: '文本', area: 'embedding' },
|
||||
{ key: 'text_rerank', label: '重排序', group: '文本', area: 'text' },
|
||||
{ key: 'image_generate', label: '图像生成', group: '图像', area: 'image' },
|
||||
{ key: 'image_edit', label: '图像编辑', group: '图像', area: 'image' },
|
||||
{ key: 'image_analysis', label: '图像理解', group: '理解', area: 'text' },
|
||||
@@ -469,7 +470,7 @@ function boolFrom(value: unknown) {
|
||||
}
|
||||
|
||||
function looksLikeCapabilityType(key: string) {
|
||||
return modelTypeDefinitionMap.has(key) || key.includes('_') || ['chat', 'image', 'video', 'audio', 'embedding', 'music', 'digital_human', 'model_3d'].includes(key);
|
||||
return modelTypeDefinitionMap.has(key) || key.includes('_') || ['chat', 'image', 'video', 'audio', 'embedding', 'rerank', 'music', 'digital_human', 'model_3d'].includes(key);
|
||||
}
|
||||
|
||||
function inferArea(type: string): CapabilityConfigArea {
|
||||
@@ -484,7 +485,7 @@ function inferArea(type: string): CapabilityConfigArea {
|
||||
}
|
||||
|
||||
function isTextLike(type: string) {
|
||||
return ['text_generate', 'image_analysis', 'video_understanding', 'audio_understanding', 'omni', 'tools_call'].includes(type);
|
||||
return ['text_generate', 'text_rerank', 'image_analysis', 'video_understanding', 'audio_understanding', 'omni', 'tools_call'].includes(type);
|
||||
}
|
||||
|
||||
function isImageLike(type: string) {
|
||||
|
||||
Reference in New Issue
Block a user