GenUI SDK Server 使用文档

GenUI SDK 对话服务，提供 OpenAI 兼容的 HTTP 接口，支持流式响应和多种 AI 服务提供商。

启动服务

安装

全局安装

bash

npm install -g @opentiny/genui-sdk-server

安装到项目

bash

npm install @opentiny/genui-sdk-server

环境配置

创建 .env 文件：

bash

BASE_URL=https://api.openai.com/v1
API_KEY=
PORT=3100

启动方式

方式一：使用 CLI 命令

bash

# 使用默认配置
npx genui-sdk-server

# 指定环境变量文件 简写为-e
npx genui-sdk-server --envFile .env.production

# 指定端口 简写为-p
npx genui-sdk-server --port 3000

# 通过设置环境变量启动(git bash)
export API_KEY= BASE_URL=https://your-llm-server.com/api && npx genui-sdk-server

方式二：编程方式

typescript

import { startServer } from '@opentiny/genui-sdk-server';
import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-opentiny-vue/meta';

startServer({
  port: 3100,
  baseURL: 'https://api.openai.com/v1',
  apiKey: '',
  maxAttempts: 10, // 端口冲突时最大尝试次数
  materialsMeta, // 物料须与前端一致；非内置默认物料时必须显式传入，见「物料配置（materialsMeta）」
});

方式三：集成到现有 Express 应用

typescript

import express from 'express';
import { equipChatCompletions } from '@opentiny/genui-sdk-server';
import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-opentiny-vue/meta';
import cors from 'cors';

const app = express();
app.use(cors());

equipChatCompletions(app, {
  route: '/chat/completions',
  apiKey: '',
  baseURL: 'https://api.openai.com/v1',
  materialsMeta, // 不传则按 framework 取内置默认物料（Vue → OpenTiny Vue，Angular → OpenTiny Angular）；其他物料须显式传入，见「物料配置（materialsMeta）」
});

app.listen(3000);

物料配置（materialsMeta）

Server 会把物料元数据（materialsMeta）注入 system prompt，让大模型按物料包中真实存在的组件名生成 schema。因此服务端使用的物料必须与前端 GenuiConfigProvider 注入的物料一致，否则大模型生成的组件名前端无法渲染（例如服务端用 Vue 物料、前端用 React 物料时，会生成 TinyButton，而 React 侧只有 Ant Design 的 Button）。

startServer / equipChatCompletions 的 materialsMeta 不传时，服务端按请求 metadata.tinygenui.framework 选择内置默认物料：

framework	服务端内置默认物料
`Vue`	`@opentiny/genui-sdk-materials-vue-opentiny-vue/meta`
`Angular`	`@opentiny/genui-sdk-materials-angular-opentiny-ng/meta`
其他 / 未指定	回落到 Vue 默认物料

只要前端物料与上表的内置默认不一致，就必须在服务端显式传入对应的 materialsMeta，包括但不限于：

前端物料	服务端需传入
React Ant Design `@opentiny/genui-sdk-materials-react-antd`	`@opentiny/genui-sdk-materials-react-antd/meta`
Vue Element Plus `@opentiny/genui-sdk-materials-vue-element-plus`	`@opentiny/genui-sdk-materials-vue-element-plus/meta`
Vue 精简集 `miniMaterials`	`miniMaterialsMeta`
自定义物料	自行提供的 `IMaterialsMeta`

以 React 前端为例：

typescript

import { startServer } from '@opentiny/genui-sdk-server';
import { materialsMeta } from '@opentiny/genui-sdk-materials-react-antd/meta';

startServer({
  port: 3100,
  baseURL: 'https://api.openai.com/v1',
  apiKey: '',
  materialsMeta, // 与前端注入的 React 物料保持一致
});

以 Vue Element Plus 前端为例：

typescript

import { startServer } from '@opentiny/genui-sdk-server';
import { materialsMeta } from '@opentiny/genui-sdk-materials-vue-element-plus/meta';

startServer({
  port: 3100,
  baseURL: 'https://api.openai.com/v1',
  apiKey: '',
  materialsMeta, // 与前端注入的 Element Plus 物料保持一致
});

CLI（npx genui-sdk-server）不提供物料参数，只能使用内置默认物料。前端一旦替换了物料（React、Element Plus、mini 精简集、自定义物料等），都必须改用「方式二：编程方式」或「方式三：集成到现有 Express 应用」显式传入 materialsMeta。

请求发起端使用

聊天补全接口

端点: POST /chat/completions

请求格式（OpenAI 兼容）：

jsonc

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": true,
  "temperature": 0.7,
  "metadata": {
    "tinygenui": "{}" // 详情参考 tinygenui 配置
  }
}

响应格式（Server-Sent Events）：

text

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: [DONE]

tinygenui 配置

通过 metadata.tinygenui 字段传递 GenUI 配置以增强大模型生成效果（JSON 字符串）：

json

{
  "framework": "Vue", // 或 "Angular" / "React"
  "strategy": "append", // "append" | "prepend" | "override"
  "customComponents": [], // 自定义组件 schema 数组
  "customExamples": [], // 自定义组件使用示例
  "customSnippets": [], // 自定义组件片段 schema 数组
  "customActions": [] // 自定义动作定义数组
}

framework: 指定前端框架（Vue、Angular 或 React），用于生成对应的渲染器配置，并决定不传 materialsMeta 时使用哪套内置默认物料（详见上文「物料配置（materialsMeta）」）
strategy: 提示词合并策略
- append: 追加到现有 system message（默认）
- prepend: 前置到现有 system message
- override: 覆盖现有 system message
customComponents: 自定义组件 schema 数组，用于扩展可用的组件列表
customExamples: 自定义组件使用示例，用于指导 LLM 生成正确的组件用法
customSnippets: 自定义组件片段 schema 数组，用于提供常用的组件组合模式
customActions: 自定义动作定义数组，用于定义可在组件中调用的动作（如提交表单、打开新页面等）

自定义组件配置示例

customComponents 配置示例：

const customComponents = [
  {
    name: '选择用户组件',
    description: '选择用户组件，用于选择用户，支持模糊搜索',
    component: 'TinyUser',
    schema: {
      properties: [
        {
          property: 'name',
          description: '搜索用户名称，支持模糊搜索',
          type: 'string',
          required: true,
        },
      ],
    },
  },
];

customExamples 配置示例：

const customExamples = [
  {
    name: '选择用户示例',
    schema: {
      componentName: 'Page',
      children: [
        {
          componentName: 'h3',
          props: {},
          children: '输入用户名搜索工号并选择用户',
        },
        {
          componentName: 'TinyUser',
          props: {
            name: '张三',
          },
        },
      ],
    },
  },
];

customSnippets 配置示例：

// 表单组合示例
const customSnippets = [
  {
    componentName: 'TinyForm',
    props: {
      labelPosition: 'top',
      labelWidth: '120px',
    },
    children: [
      {
        componentName: 'TinyFormItem',
        props: {
          label: '姓名',
          prop: 'name',
          required: true,
        },
        children: [
          {
            componentName: 'TinyInput',
            props: {
              placeholder: '请输入姓名',
            },
          },
        ],
      },
      {
        componentName: 'TinyFormItem',
        props: {
          label: '邮箱',
          prop: 'email',
        },
        children: [
          {
            componentName: 'TinyInput',
            props: {
              placeholder: '请输入邮箱',
            },
          },
        ],
      },
      {
        componentName: 'TinyFormItem',
        props: {
          label: '',
        },
        children: [
          {
            componentName: 'TinyButton',
            props: {
              type: 'primary',
              children: '提交',
            },
          },
        ],
      },
    ],
  },
];

customActions 配置示例：

const customActions = [
  {
    name: 'openPage',
    description: '打开新页面，用于页面跳转',
    parameters: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: '目标页面URL或路径',
        },
        target: {
          type: 'string',
          description: '打开方式，可选值：_self（当前窗口）、_blank（新窗口）',
        },
      },
      required: ['url', 'target'],
    },
  },
];

完整配置示例：

const requestParams = {
  'model': 'gpt-4',
  'messages': [
    {
      'role': 'system',
      'content': 'You are a helpful assistant.',
    },
    {
      'role': 'user',
      'content': 'Hello!',
    },
  ],
  'stream': true,
  'temperature': 0.7,
  'metadata': {
    'tinygenui': JSON.stringify({
      framework: 'Vue',
      strategy: 'append',
      customComponents,
      customExamples,
      customSnippets,
      customActions,
    }),
  },
};

GenUI SDK Server 使用文档 ​

启动服务 ​

安装 ​

环境配置 ​

启动方式 ​

方式一：使用 CLI 命令 ​

方式二：编程方式 ​

方式三：集成到现有 Express 应用 ​

物料配置（materialsMeta） ​

请求发起端使用 ​

聊天补全接口 ​

tinygenui 配置 ​

自定义组件配置示例 ​

GenUI SDK Server 使用文档

启动服务

安装

环境配置

启动方式

方式一：使用 CLI 命令

方式二：编程方式

方式三：集成到现有 Express 应用

物料配置（materialsMeta）

请求发起端使用

聊天补全接口

tinygenui 配置

自定义组件配置示例