🤖 AI - 如何让 AI 基于组件库（开源、私有）生成业务组件代码

app/components/BizComponentExample
├─ index.ts // 仅仅将组件内容暴露给外部
├─ interface.ts // 定义组件内部用到的所有类型，包括 interface、type、enum 等
├─ BizComponentExample.stories.tsx // 组件的 storybook 文档，包含组件不同的使用示例
├─ BizComponentExample.tsx // 组件的主体样式和主体逻辑，如果组件太大(超过 500 行)可以拆分为其它的文件，样式使用 tailwindcss 编写
├─ helpers.ts // 组件所有的工具函数存放在此 (如有)

// 任务状态
type TaskStatus = "todo" | "done";

// 任务
interface Task {
  id: string;
  description: string;
  status: TaskStatus;
}

// TodoList 组件的 props 接口
interface TodoListProps {
  // 任务列表：需要 get 请求服务端数据
  tasks: Task[];
  // 搜索任务：需要 get 请求服务端数据
  onSearchTask: (keyword: string) => void;
  // 新增任务：需要 post 新增服务端数据
  onAddTask: (task: Task) => void;
  // 删除任务：需要 delete 删除服务端数据
  onDeleteTask: (taskId: string) => void;
  // 变更任务状态：需要 put 变更服务端数据
  onUpdateTaskStatus: (taskId: string, status: TaskStatus) => void;
}

git clone https://github.com/AI-FE/ai-friendly-clean-business-component-template
cd ai-friendly-clean-business-component-template
pnpm install

<!-- 启动 storybook，查看业务组件 -->
pnpm storybook

<!-- 启动 dev，查看页面 -->
pnpm dev

app/components/BizComponentExample
├─ index.ts // 仅仅将组件内容暴露给外部
├─ interface.ts // 定义组件内部用到的所有类型，包括 interface、type、enum 等
├─ BizComponentExample.stories.tsx // 组件的 storybook 文档，包含组件不同的使用示例
├─ BizComponentExample.tsx // 组件的主体样式和主体逻辑，如果组件太大(超过 500 行)可以拆分为其它的文件，样式使用 tailwindcss 编写
├─ helpers.ts // 组件所有的工具函数存放在此 (如有)

# Role: 前端业务组件开发专家

## Profile

- author: lv.liu
- version: 0.1
- language: 中文
- description: 作为一名资深的前端开发工程师，你能够熟练掌握编码原则和设计模式来进行业务组件的开发。

## Goals

- 能够清楚地理解用户提出的业务组件需求

- 根据用户的描述生成完整的符合代码规范的业务组件代码

## Constraints

- 业务组件中用到的所有组件都来源于 `antd` 组件库

- 组件必须遵循数据解耦原则：
  - 所有需要从服务端获取的数据必须通过 props 传入，禁止在组件内部直接发起请求
  - 数据源相关的 props 必须提供以下内容：
    - 初始化数据（initialData/defaultData 等）
  - 所有会触发数据变更的操作必须通过回调函数形式的 props 传递，例如：
    - onDataChange - 数据变更回调
    - onSearch - 搜索回调
    - onPageChange - 分页变更回调
    - onFilterChange - 筛选条件变更回调
    - onSubmit - 表单提交回调

## Workflows

第一步：根据用户的需求，分析实现需求所需要哪些`antd`组件。

第二步：根据分析出来的组件，生成对应的业务组件代码，业务组件的规范模版如下：

组件包含 5 类文件，对应的文件名称和规则如下:

    1、index.ts（对外导出组件）
    这个文件中的内容如下：
    export { default as [组件名] } from './[组件名]';
    export type { [组件名]Props } from './interface';

    2、interface.ts
    这个文件中的内容如下，请把组件的props内容补充完整：
    interface [组件名]Props {}
    export type { [组件名]Props };

    3、[组件名].stories.tsx
    这个文件中使用 import type { Meta, StoryObj } from '@storybook/react' 给组件写一个storybook文档，必须根据组件的props写出完整的storybook文档，针对每一个props都需要进行mock数据。

    4、[组件名].tsx
    这个文件中存放组件的真正业务逻辑和样式，如果组件太大(超过500行)可以拆分为其它的文件，样式使用 tailwindcss 编写

    5、helpers.ts
    组件所有的工具函数存放在此 (如有)

## Initialization

作为前端业务组件开发专家，你十分清晰你的[Goals]，同时时刻记住[Constraints], 你将用清晰和精确的语言与用户对话，并按照[Workflows]逐步思考，逐步进行回答，竭诚为用户提供代码生成服务。

请帮我生成一个提示词，能够根据用户输入的需求来生成符合下面 LangGPT md 格式的提示词:

https://github.com/langgptai/LangGPT

# Role: LangGPT Prompt Generator

## Profile

- Author: AI Assistant
- Version: 1.0
- Language: 中文
- Description: 你是一个专业的 LangGPT 提示词生成器，擅长根据用户需求分析任务，提取关键信息，并生成符合 LangGPT 结构化格式的高质量提示词。

### Skills

1. **任务分析能力**：能够深入理解用户的需求和目标，识别任务类型和核心要求
2. **结构化设计能力**：熟悉 LangGPT 框架的各个模块及其用法，能够合理组织信息
3. **角色定义能力**：根据任务需求定义合适的 AI 角色、技能和特性
4. **工作流程设计能力**：能够将复杂任务拆解为清晰的步骤流程
5. **约束条件设定能力**：识别并定义必要的规则和约束，避免输出偏差

## Goal

- **Outcome**：为用户的需求生成一个完整、专业、可用的 LangGPT 格式提示词
- **Done Criteria**：
  - 生成的提示词包含 Role、Profile、Rules、Workflow、Initialization 等核心模块
  - 每个模块的内容准确、具体、可执行
  - 符合 LangGPT 的 Markdown 格式规范
  - 生成的提示词可以直接复制使用
- **Non-Goals**：
  - 不需要解释 LangGPT 框架的原理（除非用户特别要求）
  - 不需要演示生成的提示词的使用效果
  - 不需要修改或优化用户提供的内容（除非有矛盾）

## Rules

1. 始终遵循 LangGPT 的结构化格式规范
2. 根据任务复杂度，合理选择需要包含的模块（核心模块必须包含）
3. 如果用户提供的信息不完整，主动询问补充必要信息
4. 生成的每个模块的内容应该具体、清晰、可执行
5. 保持专业、简洁的文风，避免冗余描述
6. 使用 Markdown 格式，正确使用标题层级（# ## ###）
7. 变量引用使用尖括号格式，如 `<Role>`、`<Rules>` 等

## Workflow

1. **理解需求**：仔细阅读用户的需求描述，理解任务的本质和目标
2. **提取信息**：从用户描述中提取关键信息：
   - 任务类型和领域
   - 期望的输出类型
   - 特殊要求或约束
   - 需要处理的输入类型
3. **设计角色**：基于任务需求设计合适的 AI 角色：
   - 确定角色名称和描述
   - 定义必要的技能和能力
   - 设置角色的行为准则
4. **规划流程**：将任务拆解为清晰的工作步骤，确保逻辑顺序合理
5. **设定规则**：识别必要的约束条件和行为规则
6. **撰写模板**：按照 LangGPT 格式撰写完整的提示词模板
7. **优化完善**：检查生成的提示词，确保格式正确、内容完整、逻辑清晰

## Output Format

生成的提示词必须遵循以下格式：

# Role: [角色名称]

## Profile

- Author: [作者]
- Version: [版本号]
- Language: [语言]
- Description: [角色描述]

### Skill-1

1. [技能描述 1]
2. [技能描述 2]

### Skill-2

[技能描述]

## Rules

1. [规则 1]
2. [规则 2]

## Workflow

1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

## Initialization

[初始化内容，引用变量如 <Role>、<Rules> 等]

根据需要，还可以添加以下可选模块：

- **Goals**：明确目标、完成标准和排除项
- **Constraints**：额外的约束条件
- **Examples**：示例输入输出
- **Style**：输出风格要求
- **Output**：输出格式定义
- **Commands**：自定义命令（如 /help、/continue）
- **Reminder**：上下文提醒机制

## Initialization

你好！我是 LangGPT 提示词生成器。

我可以帮助你根据具体需求生成符合 LangGPT 结构化格式的高质量提示词。

请告诉我：

1. 你需要什么样的 AI 助手或工具？
2. 它的主要功能是什么？
3. 有什么特殊要求或约束吗？

我会根据你的需求，生成一个完整的 LangGPT 格式提示词。

参考 @.prompt/langgpt-prompt.md 帮我生成一个提示词，能够根据用户输入的设计稿或者自然语言需求来生成业务组件代码:

- 技术栈是：`React + TailwindCSS + antd`

- 业务组件遵循的文件结构和代码规范如下所示：
  ├─ index.ts // 仅仅将组件内容暴露给外部
  ├─ interface.ts // 定义组件内部用到的所有类型，包括 interface、type、enum 等
  ├─ BizComponentExample.stories.tsx // 组件的 storybook 文档，包含组件不同的使用示例
  ├─ BizComponentExample.tsx // 组件的主体样式和主体逻辑，如果组件太大(超过 500 行)可以拆分为其它的文件，样式使用 tailwindcss 编写
  ├─ helpers.ts // 组件所有的工具函数存放在此 (如有)

- 业务组件遵循前后端状态分离原则：所有需要请求服务端数据的操作，都通过 props 暴露个外部的页面来进行对接联调。生成的提示词的内容保存到@.prompt/antd-component-codegen.md 。

# Role: AntD 业务组件代码生成器

## Profile

- Author: AI Assistant
- Version: 1.0
- Language: 中文
- Description: 根据用户提供的设计稿或自然语言需求，使用 React + TailwindCSS + antd + TypeScript 生成符合规范的业务组件代码，并输出完整文件结构与 Storybook 示例。

### 技能

1. 需求理解：解析设计稿/自然语言需求，提炼组件功能、状态、交互、数据结构。
2. 架构设计：按前后端状态分离原则设计 props 与回调，定义清晰的类型接口。
3. UI 实现：使用 TailwindCSS 及 antd 组件实现高质量、响应式界面。
4. 文档示例：编写 Storybook 示例，覆盖常见状态与交互。
5. 代码规范：严格遵循文件结构与导出规范，保持可维护性。

## Rules

1. 技术栈：React 18+、TypeScript、TailwindCSS、Ant Design、Storybook。
2. 文件结构（组件名以 BizComponentExample 为例）：
   - `index.ts`：仅导出组件与类型。
   - `interface.ts`：定义组件内部用到的全部类型（interface/type/enum）。
   - `BizComponentExample.tsx`：主体样式与逻辑，超 500 行可拆分；使用 TailwindCSS。
   - `BizComponentExample.stories.tsx`：Storybook 文档，包含多种使用示例与状态。
   - `helpers.ts`：工具函数（如需要）。
3. 前后端状态分离：禁止在组件内发起请求；所有业务数据通过 props 传入；所有增删改查等业务操作通过 `on*` 回调暴露；组件内部状态仅用于 UI 控制。
4. 类型与导出：使用 `React.FC`；所有对外类型从 `interface.ts` 导出；`index.ts` 只做导出聚合。
5. UI 规范：优先使用 antd 组件；样式用 TailwindCSS 类名；保持可访问性与响应式；命名与结构简洁。
6. 代码质量：必要时拆分辅助逻辑到 `helpers.ts`；避免重复；提供默认值与空态处理；注释仅在逻辑复杂处简明说明。

## Workflow

1. 需求解析：识别输入类型（设计稿/自然语言），提取数据结构、状态、交互、边界条件、UI 细节。
2. 类型设计：在 `interface.ts` 定义数据模型、Props、枚举/类型别名；回调以 `on` 前缀暴露全部业务操作。
3. 组件实现：在 `BizComponentExample.tsx` 使用 React + TailwindCSS + antd 完成布局、交互与 UI 状态管理；不处理后端数据获取。
4. 工具函数：如有通用逻辑，抽到 `helpers.ts` 并在组件中引用。
5. 导出：`index.ts` 聚合导出组件与类型。
6. Storybook：`BizComponentExample.stories.tsx` 提供至少一个默认示例和若干状态示例（空态/加载/错误/交互），使用 mock 数据与回调。
7. 自检清单：核对前后端分离、文件齐全、类型完整、导出正确、无请求、UI 用 TailwindCSS 且优先 antd、示例覆盖常见状态。

## Initialization

你现在是一名资深的 React + TailwindCSS + antd 前端工程师。请等待用户输入的设计稿描述或自然语言需求，然后按上述 Rules 与 Workflow 直接输出完整的组件代码与文件内容，遵循规定的文件结构与前后端分离原则。若需求不全，先用中文询问所缺细节（数据结构、状态、交互、异常/空态、受控/非受控需求）。

table.md

<!-- 这里是 Table 组件的知识库数据 -->

input.md

<!-- 这里是 Input 组件的知识库数据 -->

# Table

## When To Use（使用场景）

Table 组件用于展示数据，通常用于展示列表数据。

## API（组件的 API）

- data: Array<{ name: string, age: number }>
- columns: Array<{ title: string, dataIndex: string }>

git clone https://github.com/AI-FE/private-bizcomponent-website.git

pnpm install

cd packages/@private-basic-components
node ai-docs/format-docs.js

const fs = require("fs");
const path = require("path");

const inputDirectory = path.join(__dirname, "../components");
const outputFileCSVPath = path.join(__dirname, "basic-components.txt");

const dataSources = [];

function saveToTxt() {
  // 将dataSources中的内容拼接成一个字符串，每个内容之间用效果展示效果展示-split line效果展示效果展示-分割
  const csvContent = dataSources.join(
    "\n效果展示效果展示-split line效果展示效果展示-\n",
  );
  // 将csvContent转换为带BOM的UTF-8格式防止用excel打开时中文乱码
  const csvWithBOM = `\ufeff${csvContent}`;
  // 将csvWithBOM写入到outputFileCSVPath文件中
  fs.writeFileSync(outputFileCSVPath, csvWithBOM, "utf8");
  console.log("基础组件知识库文件已保存");
}

function collectDoc(content) {
  // 从content中提取组件名称
  const match = content.match(/\btitle\b:\s*(.*)/);
  // 提取组件名称
  const componentName = match?.[1]?.trim();
  // 搜索API部分的开始位置
  const apiStartIndex = content.search("## API");
  // 搜索When To Use部分的开始位置
  const descriptionIndex = content.search("## When To Use");

  // 如果API或When To Use部分没有找到，则打印警告并返回
  if (apiStartIndex === -1 || descriptionIndex === -1) {
    console.warn(
      `API or description section not found for component: ${componentName}`,
    );
    return;
  }

  // 提取API部分的内容
  const firstHandleContent = content
    .substring(apiStartIndex + "## API".length)
    .trim();
  // 提取When To Use部分的内容
  const firstHandelDescriptionContent = content
    .substring(descriptionIndex + "## When To Use".length)
    .trim();

  // 搜索API部分的结束位置
  const apiEndIndex = firstHandleContent.search(/(?<!#)##(?!#)/);
  // 搜索When To Use部分的结束位置
  const descriptionEndIndex =
    firstHandelDescriptionContent.search(/(?<!#)##(?!#)/);
  // 提取API部分的内容
  // 如果API部分的结束位置大于0，则提取API部分的内容，否则提取整个API部分的内容
  const apiContent = firstHandleContent
    .substring(0, apiEndIndex >= 0 ? apiEndIndex : undefined)
    .trim();
  // 如果When To Use部分的结束位置大于0，则提取When To Use部分的内容，否则提取整个When To Use部分的内容
  const descriptionContent = firstHandelDescriptionContent
    .substring(0, descriptionEndIndex >= 0 ? descriptionEndIndex : undefined)
    .trim();
  // 将API部分和When To Use部分的内容拼接成一个字符串
  const csvFormat = `
    The documentation for the ${componentName} basic UI components
    <when-to-use>
    ${descriptionContent}
    </when-to-use>

    <API>
    ${apiContent}
    </API>
    `;
  // 将csvFormat添加到dataSources中
  dataSources.push(csvFormat);
}

function processFiles(directoryPath) {
  // 读取目录下的所有文件
  const files = fs.readdirSync(directoryPath);
  // 遍历所有文件
  files.forEach((file) => {
    // 拼接文件路径
    const filePath = path.join(directoryPath, file);
    // 判断是否是目录
    if (fs.statSync(filePath).isDirectory()) {
      // 如果是子目录，则递归处理
      processFiles(filePath);
    } else if (file === "index.en-US.md") {
      // 如果文件名是 "index-en-US.md"，则读取内容并追加到输出文件
      const content = fs.readFileSync(filePath, "utf8");
      // 收集文档内容
      collectDoc(content);
    }
  });
}

// 递归遍历目录并处理文件
function generatedDOC(directoryPath) {
  processFiles(directoryPath);
  saveToTxt();
  console.log(
    `Successfully generated API documentation to ${outputFileCSVPath}`,
  );
}
// 开始处理文件
generatedDOC(inputDirectory);

# Role: 前端业务组件开发专家

## Profile

- author: lv
- version: 0.1
- language: 中文
- description: 你作为一名资深的前端开发工程师，拥有数十年的一线编码经验，特别是在前端组件化方面有很深的理解，熟练掌握编码原则，如功能职责单一原则、开放—封闭原则，对于设计模式也有很深刻的理解。

## Goals

- 能够清楚地理解用户提出的业务组件需求.

- 根据用户的描述生成完整的符合代码规范的业务组件代码。

## Constraints

- 业务组件中用到的所有组件都来源于 `import {  } from "@private-basic-components"` 组件库。

- 必须遵循知识库<API> </API>中组件的 props 来实现业务组件

## Workflows

第一步：结合用户需求理解我提供给你的`@private-basic-components`组件知识库数据。

- 我提供的知识库数据中，包含了实现这个需求可能需要的`@private-basic-components`组件知识。

- 其中`<when-to-use>`标签中，描述了组件的使用场景，`<API>`标签中，描述了组件的 props api 类型定义。

第二步：请根据用户的需求以及我提供的知识库数据，生成对应的业务组件代码，业务组件的规范模版如下：

组件包含 4 类文件，对应的文件名称和规则如下:

    1、index.ts（对外导出组件）
    这个文件中的内容如下：
    export { default as [组件名] } from './[组件名]';
    export type { [组件名]Props } from './interface';

    2、interface.ts
    这个文件中的内容如下，请把组件的props内容补充完整：
    interface [组件名]Props {}
    export type { [组件名]Props };

    3、[组件名].stories.tsx
    这个文件中使用 import type { Meta, StoryObj } from '@storybook/react' 给组件写一个storybook文档，必须根据组件的props写出完整的storybook文档，针对每一个props都需要进行mock数据。

    4、[组件名].tsx
    这个文件中存放组件的真正业务逻辑和样式，样式请用tailwindcss来编写

## Initialization

作为前端业务组件开发专家，你十分清晰你的[Goals]，同时时刻记住[Constraints], 你将用清晰和精确的语言与用户对话，并按照[Workflows]逐步思考，逐步进行回答，竭诚为用户提供代码生成服务。

├── app
│ ├── api // api 路由
│ │ ├── openai
│ │ ├── vercelai
│ ├── components // 业务组件
│ ├── openai-sdk // 对接 OpenAI SDK 的 page
│ ├── vercel-ai // 对接 Vercel AI 的 page
│ ├── page.tsx // 入口
├── lib
│ ├── db // 数据库
│ │ ├── openai
│ │ │ ├── schema.ts
│ │ │ ├── selectors.ts
│ │ │ ├── actions.ts
│ │ ├── vercelai
│ │ │ ├── schema.ts
│ │ │ ├── selectors.ts
│ │ │ ├── actions.ts

git clone https://github.com/OweQian/private-component-codegen.git

cp .env.template .env

# 数据库连接字符串：从supabase中获取（https://supabase.com/）
DATABASE_URL=postgresql://
# 嵌入模型
EMBEDDING=text-embedding-ada-002
# 大模型 API Key
AI_KEY=sk-xxx
# 大模型 API Base URL
AI_BASE_URL=https://api
# 大模型
MODEL=claude-3-5-sonnet-latest

# pnpm version >= 9
pnpm install

# 启动storybook业务组件文档
pnpm storybook

# 启动项目
pnpm dev

使用 drizzle-orm/pg-core 创建一个 PostgreSQL 数据表 schema，用于存储 OpenAI embeddings。表名为 'open_ai_embeddings'，包含以下字段:

- id: 使用 nanoid 生成的主键，varchar(191) 类型
- content: 文本内容，text 类型，不允许为空
- embedding: 向量类型字段，维度为 1536，不允许为空

同时需要创建一个使用 HNSW 算法的向量索引，用于余弦相似度搜索。

import { nanoid } from "nanoid";
import { index, pgTable, text, varchar, vector } from "drizzle-orm/pg-core";

/**
 * OpenAI embeddings 表
 */
export const openAiEmbeddings = pgTable(
  "open_ai_embeddings",
  {
    /**
     * 唯一标识
     */
    id: varchar("id", { length: 191 })
      .primaryKey()
      .$defaultFn(() => nanoid()),
    /**
     * 内容
     */
    content: text("content").notNull(),
    /**
     * 嵌入向量
     */
    embedding: vector("embedding", { dimensions: 1536 }).notNull(),
  },
  (table) => ({
    /**
     * 索引
     */
    openAiEmbeddingIndex: index("open_ai_embedding_index").using(
      /**
       * 索引方法
       */
      "hnsw",
      /**
       * 索引操作
       */
      table.embedding.op("vector_cosine_ops"),
    ),
  }),
);

pnpm db:generate

pnpm db:migrate

创建一个 server action function，能够接收外部的数据源，保存到 db 中，function 入参是：embeddings: Array<{ embedding: number[]; content: string }>，生成的代码写到 action.ts 中。

"use server";

import { db } from "..";
import { openAiEmbeddings as embeddingsTable } from "./schema";

export const createResource = async (
  embeddings: Array<{ embedding: number[]; content: string }>,
) => {
  try {
    /**
     * 插入嵌入向量
     */
    await db.insert(embeddingsTable).values(
      embeddings.map((embedding) => ({
        ...embedding,
      })),
    );

    return "Resource successfully created and embedded.";
  } catch (error) {
    console.log("error", error);
    return error instanceof Error && error.message.length > 0
      ? error.message
      : "Error, please try again.";
  }
};

使用 OpenAI SDK 创建一个函数，将输入的文本字符串转换为向量嵌入（embeddings）。支持将文本按特定分隔符分块处理，分隔符的默认值为 '效果展示效果展示-split line效果展示效果展示-'，每个文本块都生成对应的 embedding 向量，并返回包含原文本和向量的结果数组。

import { env } from "@/lib/env.mjs";
import OpenAI from "openai";
import { HttpsProxyAgent } from "https-proxy-agent";

const embeddingAI = new OpenAI({
  apiKey: env.AI_KEY,
  baseURL: env.AI_BASE_URL,
  /**
   * 代理配置
   */
  ...(env.HTTP_AGENT ? { httpAgent: new HttpsProxyAgent(env.HTTP_AGENT) } : {}),
});

const generateChunks = (input: string): string[] => {
  return input.split("-------split line-------");
};

/**
 * 生成嵌入向量
 * @param value 输入文本
 * @returns 嵌入向量
 */
export const generateEmbeddings = async (
  value: string,
): Promise<Array<{ embedding: number[]; content: string }>> => {
  const chunks = generateChunks(value);

  const embeddings = await Promise.all(
    chunks.map(async (chunk) => {
      /**
       * 生成嵌入向量
       */
      const response = await embeddingAI.embeddings.create({
        model: env.EMBEDDING,
        input: chunk,
      });
      return {
        content: chunk,
        embedding: response.data[0].embedding,
      };
    }),
  );

  return embeddings;
};

import fs from "fs";
import { env } from "@/lib/env.mjs";
import { createResource } from "@/lib/db/openai/actions";
import { generateEmbeddings } from "./embedding";

console.log("env.EMBEDDING", env.EMBEDDING);

/**
 * 入库
 */
export const generateEmbeddingsFromDocs = async () => {
  console.log("start reading docs");
  /**
   * 读取文档
   */
  const docs = fs.readFileSync("./ai-docs/basic-components.txt", "utf8");

  console.log("start generating embeddings");
  /**
   * 生成嵌入向量
   */
  const embeddings = await generateEmbeddings(docs);

  console.log("start creating resource");
  /**
   * 创建资源，插入到数据库表
   */
  await createResource(embeddings);

  console.log("success~~~");
};

generateEmbeddingsFromDocs();

"openai:embedDocs": "tsx app/api/openai/embedDocs.ts"

pnpm openai:embedDocs

创建一个基于向量嵌入的语义相似度搜索函数。该函数需要：

- 接收一个查询向量（embedding）作为输入
- 计算输入向量与数据库中存储的向量之间的余弦相似度
- 筛选出相似度高于指定阈值的结果
- 返回相似度最高的 N 个结果，包含原始内容和相似度分数
- 使用 SQL ORM 实现数据库查询

"use server";

import { cosineDistance } from "drizzle-orm/sql";
import { openAiEmbeddings } from "./schema";
import { db } from "@/lib/db";
import { sql, gt, desc } from "drizzle-orm";

export const findSimilarContent = async (userQueryEmbedded: number[]) => {
  /**
   * 计算相似度
   */
  const similarity = sql<number>`1 - (${cosineDistance(
    openAiEmbeddings.embedding,
    userQueryEmbedded,
  )})`;
  /**
   * 查找相关内容
   */
  const similarGuides = await db
    .select({
      content: openAiEmbeddings.content,
      similarity,
    })
    .from(openAiEmbeddings)
    .where(gt(similarity, 0.5))
    .orderBy((t) => desc(t.similarity))
    .limit(4);
  return similarGuides;
};

/**
 * 生成单个嵌入向量
 * @param value 输入文本
 * @returns 嵌入向量
 */
export const generateEmbedding = async (value: string): Promise<number[]> => {
  const input = value.replaceAll("\\n", " ");
  const response = await embeddingAI.embeddings.create({
    model: env.EMBEDDING,
    input,
  });
  return response.data[0].embedding;
};

/**
 * 查找相关内容
 * @param userQuery 用户查询
 * @returns 相关内容
 */
export const findRelevantContent = async (
  userQuery: string,
): Promise<{ content: string; similarity: number }[]> => {
  const userQueryEmbedded = await generateEmbedding(userQuery);
  return findSimilarContent(userQueryEmbedded);
};

import { ChatCompletionMessageParam } from "openai/resources/chat/completions";

export type OpenAIRequest = {
  messages: ChatCompletionMessageParam[];
};

创建一个基于 Next.js 的流式 AI 对话 API 路由处理器，使用 OpenAI API 实现。该接口需要实现以下功能：

1. 通过 POST 请求接收对话消息
2. 基于最后一条消息使用向量嵌入（embeddings）查找相关内容
3. 创建 OpenAI 的流式对话补全，要求：
   - 将相关内容整合到系统提示词中
   - 使用服务器发送事件（SSE）进行流式响应
   - 在流中同时返回 AI 响应片段和相关内容

/**
 * OpenAI API 路由处理文件
 *
 * 该文件实现了基于 RAG（检索增强生成）的聊天 API 端点，主要功能包括：
 * 1. 接收聊天消息请求
 * 2. 通过向量检索查找相关内容（RAG）
 * 3. 调用 OpenAI API 生成流式响应
 * 4. 以 Server-Sent Events (SSE) 格式返回结果
 */

import OpenAI from "openai";
import { HttpsProxyAgent } from "https-proxy-agent";
import { OpenAIRequest } from "./types";
import { ChatModel } from "openai/resources/index.mjs";
import { findRelevantContent } from "./embedding";
import { getSystemPrompt } from "@/lib/prompt";
import { env } from "@/lib/env.mjs";

/**
 * 创建 SSE (Server-Sent Events) 格式的数据块
 *
 * @param relevantContent - 检索到的相关内容数组，包含内容和相似度分数
 * @param aiResponse - AI 响应的文本内容（通常是流式响应中的增量内容）
 * @returns 编码后的 SSE 格式数据（UTF-8 字节数组）
 */
const createEnqueueContent = (
  relevantContent: Array<{ content: string; similarity: number }>,
  aiResponse: string,
) => {
  const data = {
    relevantContent: relevantContent || [],
    aiResponse: aiResponse || "",
  };

  // 将数据编码为 SSE 格式：event: message\ndata: {...}\n\n
  return new TextEncoder().encode(
    `event: message\ndata: ${JSON.stringify(data)}\n\n`,
  );
};

/**
 * POST 请求处理函数
 *
 * 处理聊天请求，执行以下步骤：
 * 1. 解析请求体获取消息列表
 * 2. 初始化 OpenAI 客户端（支持代理配置）
 * 3. 提取最后一条消息内容用于 RAG 检索
 * 4. 通过向量检索查找相关内容
 * 5. 构建包含系统提示词的消息列表
 * 6. 调用 OpenAI API 获取流式响应
 * 7. 将响应转换为 SSE 流返回给客户端
 *
 * @param req - HTTP 请求对象
 * @returns 包含 SSE 流的 Response 对象，或错误响应
 */
export async function POST(req: Request) {
  const request: OpenAIRequest = await req.json();
  const { messages } = request;

  try {
    // 初始化 OpenAI 客户端
    // 支持通过环境变量配置代理（用于需要代理访问的场景）
    const openai = new OpenAI({
      apiKey: env.AI_KEY,
      baseURL: env.AI_BASE_URL,
      ...(env.HTTP_AGENT
        ? { httpAgent: new HttpsProxyAgent(env.HTTP_AGENT) }
        : {}),
    });

    // 获取最后一条消息（用户的最新输入）
    const lastMessage = messages[messages.length - 1];

    // 提取最后一条消息的文本内容
    // 支持两种格式：字符串或消息内容对象数组
    const lastMessageContentString =
      Array.isArray(lastMessage.content) && lastMessage.content.length > 0
        ? lastMessage.content
            .map((c) => (c.type === "text" ? c.text : ""))
            .join("")
        : (lastMessage.content as string);

    // 通过向量检索查找与用户输入相关的内容（RAG）
    const relevantContent = await findRelevantContent(lastMessageContentString);

    console.log("relevantContent", relevantContent);
    // 创建 OpenAI 聊天完成请求
    // 使用流式响应以支持实时返回结果
    const result = openai.chat.completions.create({
      model: (env.MODEL as ChatModel) || "gpt-4o",
      max_tokens: 4096,
      stream: true, // 启用流式响应
      messages: [
        {
          role: "system",
          // 将检索到的相关内容注入到系统提示词中
          content: getSystemPrompt(
            relevantContent.map((c) => c.content).join("\n"),
          ),
        },
        ...messages, // 包含用户的历史消息
      ],
    });

    // 捕获创建请求时的错误
    await result.catch((error) => {
      throw error;
    });

    // 创建可读流，用于将 OpenAI 的流式响应转换为 SSE 格式
    const stream = new ReadableStream({
      async start(controller) {
        try {
          // 遍历 OpenAI 返回的流式数据块
          for await (const chunk of await result) {
            // 将每个数据块编码为 SSE 格式并加入队列
            controller.enqueue(
              createEnqueueContent(
                relevantContent, // 每次响应都包含检索到的相关内容
                chunk?.choices?.[0]?.delta?.content || "", // 提取增量内容
              ),
            );
          }
        } catch (err) {
          console.error("Stream error:", err);
          controller.error(err);
        } finally {
          // 确保流被正确关闭
          controller.close();
        }
      },
      cancel() {
        // 处理流被取消的情况
        console.log("Stream cancelled");
      },
    });

    // 返回 SSE 格式的响应
    return new Response(stream, {
      headers: {
        "Content-Type": "text/event-stream", // SSE 内容类型
        "Cache-Control": "no-cache", // 禁用缓存
        Connection: "keep-alive", // 保持连接活跃
      },
    });
  } catch (error: unknown) {
    // 错误处理：返回 400 错误响应
    console.error("error catch", error);
    if (error instanceof Error) {
      return new Response(error.message, {
        status: 400,
        statusText: "Bad Request",
      });
    }
    return new Response("An unknown error occurred", {
      status: 400,
      statusText: "Bad Request",
    });
  }
}

"use client";

import { ChatMessages } from "../components/ChatMessages";

const Home = () => {
  return (
    <ChatMessages
      messages={[]}
      input={""}
      handleInputChange={() => {}}
      onSubmit={() => {}}
      isLoading={false}
      messageImgUrl={""}
      setMessagesImgUrl={() => {}}
      onRetry={() => {}}
    />
  );
};

export default Home;

对接 OpenAI API 数据

"use client";

/**
 * OpenAI SDK 聊天界面组件
 *
 * 该组件实现了与 OpenAI API 的交互，支持：
 * - 文本和图片消息的发送
 * - 流式响应（SSE）的接收和处理
 * - RAG（检索增强生成）相关文档的显示
 * - 消息重试功能
 */

import { useState } from "react";
import { nanoid } from "nanoid";
import { Message } from "../components/ChatMessages/interface";
import ChatMessages from "../components/ChatMessages/ChatMessages";
import { OpenAIRequest } from "../api/openai/types";

const Home = () => {
  // 用户输入的文本内容
  const [input, setInput] = useState("");
  // 聊天消息列表
  const [messages, setMessages] = useState<Message[]>([]);
  // 消息中附加的图片 URL
  const [messageImgUrl, setMessageImgUrl] = useState("");
  // 是否正在加载（发送请求或接收响应中）
  const [isLoading, setIsLoading] = useState(false);

  /**
   * 处理输入框内容变化
   * @param e - 输入框的 change 事件
   */
  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setInput(e.target.value);
  };

  /**
   * 发送消息到 OpenAI API 并处理流式响应
   *
   * 该函数执行以下操作：
   * 1. 更新消息列表并设置加载状态
   * 2. 发送 POST 请求到 /api/openai
   * 3. 使用 ReadableStream 读取 SSE（Server-Sent Events）流式响应
   * 4. 解析每个数据块，提取 AI 响应和 RAG 相关文档
   * 5. 实时更新消息内容
   *
   * @param newMessages - 包含新用户消息的完整消息列表
   */
  const handleSendMessage = async (newMessages: Message[]) => {
    try {
      // 更新消息列表（包含用户刚发送的消息）
      setMessages(newMessages as Message[]);
      setIsLoading(true);

      // 发送请求到 OpenAI API
      const response = await fetch("/api/openai", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          messages: newMessages,
        } as OpenAIRequest),
      });

      // 获取流式响应的读取器
      const reader = response?.body?.getReader();
      console.log("reader", reader, response);
      const textDecoder = new TextDecoder();
      // 累积接收到的 AI 响应文本
      let received_stream = "";
      // 为助手消息生成唯一 ID
      const id = nanoid();
      // 缓冲区，用于处理不完整的 SSE 消息
      let buffer = "";

      // 循环读取流式数据
      while (true) {
        if (!reader) break;
        const { done, value } = await reader.read();

        // 如果流结束，退出循环
        if (done) {
          break;
        }

        // 将新的数据块添加到缓冲区
        buffer += textDecoder.decode(value, { stream: true });

        // SSE 消息以 \n\n 分隔，处理缓冲区中的所有完整消息
        const messages = buffer.split("\n\n");
        // 保留最后一个不完整的消息在缓冲区中，等待下次数据到达
        buffer = messages.pop() || "";

        // 处理每个完整的 SSE 消息
        for (const message of messages) {
          if (!message.trim()) continue;

          // SSE 格式：每行一个字段，data: 行包含实际数据
          const lines = message.split("\n");
          const dataLine = lines.find((line) => line.startsWith("data:"));

          if (dataLine) {
            // 提取 data: 后的 JSON 数据
            const jsonData = dataLine.slice(5).trim();
            try {
              // 解析 JSON，包含 AI 响应和 RAG 相关文档
              const { relevantContent, aiResponse } = JSON.parse(jsonData) as {
                relevantContent: Array<{ content: string; similarity: number }>;
                aiResponse: string;
              };
              // 累积 AI 响应文本
              received_stream += aiResponse;

              // 更新消息列表
              setMessages((messages) => {
                // 如果助手消息已存在，更新它
                if (messages.find((message) => message.id === id)) {
                  return messages.map((message) => {
                    if (message.id === id) {
                      return {
                        ...message,
                        content: received_stream,
                        // 将 RAG 相关文档转换为消息格式
                        ragDocs: relevantContent.map(
                          ({ content, similarity }) => ({
                            id: nanoid(),
                            content: content,
                            score: similarity,
                          }),
                        ),
                      };
                    }
                    return message;
                  });
                }
                // 如果助手消息不存在，创建新消息
                return [
                  ...messages,
                  {
                    id,
                    role: "assistant",
                    content: received_stream,
                    ragDocs: relevantContent.map(({ content, similarity }) => ({
                      id: nanoid(),
                      content: content,
                      score: similarity,
                    })),
                  },
                ];
              });
            } catch (e) {
              console.error("Error parsing SSE data:", e);
            }
          }
        }
      }

      // 清空输入框和图片 URL，结束加载状态
      setInput("");
      setMessageImgUrl("");
      setIsLoading(false);
    } catch (error) {
      console.error(error);
      setIsLoading(false);
      // 如果请求失败，且最后一条消息是用户消息，则移除它
      // 这样可以避免在界面上显示未得到响应的用户消息
      setMessages((messages) =>
        messages.length > 0 && messages[messages.length - 1].role === "user"
          ? messages.slice(0, -1)
          : messages,
      );
    }
  };

  /**
   * 处理表单提交
   *
   * 将用户输入（文本和可选的图片）添加到消息列表并发送
   * 如果存在图片 URL，则创建多模态消息（包含图片和文本）
   */
  const handleSubmit = async () => {
    await handleSendMessage([
      ...messages,
      {
        id: nanoid(),
        role: "user",
        // 如果有图片，创建多模态消息格式；否则只发送文本
        content: messageImgUrl
          ? [
              { type: "image_url", image_url: { url: messageImgUrl } },
              { type: "text", text: input },
            ]
          : input,
      },
    ]);
  };

  /**
   * 重试指定消息
   *
   * 从消息列表中移除指定消息及其之后的所有消息，
   * 然后重新发送该消息之前的所有消息
   *
   * @param id - 要重试的消息 ID
   */
  const handleRetry = (id: string) => {
    const index = messages.findIndex((message) => message.id === id);
    // 如果找到消息且不是第一条，则重试
    if (index > 0) {
      // 获取该消息之前的所有消息
      const previousMessages = messages.slice(0, index);
      handleSendMessage(previousMessages);
    }
  };

  return (
    <ChatMessages
      messages={messages}
      input={input}
      handleInputChange={handleInputChange}
      onSubmit={handleSubmit}
      isLoading={isLoading}
      messageImgUrl={messageImgUrl}
      setMessagesImgUrl={setMessageImgUrl}
      onRetry={handleRetry}
    />
  );
};

export default Home;

import { nanoid } from "nanoid";
import { index, pgTable, text, varchar, vector } from "drizzle-orm/pg-core";

/**
 * Vercel AI embeddings 表
 */
export const vercelAiEmbeddings = pgTable(
  "vercel_ai_embeddings",
  {
    /**
     * 唯一标识
     */
    id: varchar("id", { length: 191 })
      .primaryKey()
      .$defaultFn(() => nanoid()),
    /**
     * 内容
     */
    content: text("content").notNull(),
    /**
     * 嵌入向量
     */
    embedding: vector("embedding", { dimensions: 1536 }).notNull(),
  },
  (table) => ({
    /**
     * 索引
     */
    vercelAiEmbeddingIndex: index("vercel_ai_embedding_index").using(
      /**
       * 索引方法
       */
      "hnsw",
      /**
       * 索引操作
       */
      table.embedding.op("vector_cosine_ops"),
    ),
  }),
);

"use server";

import { db } from "..";
import { vercelAiEmbeddings as embeddingsTable } from "./schema";

export const createResource = async (
  embeddings: Array<{ embedding: number[]; content: string }>,
) => {
  try {
    /**
     * 插入嵌入向量
     */
    await db.insert(embeddingsTable).values(
      embeddings.map((embedding) => ({
        ...embedding,
      })),
    );

    return "Resource successfully created and embedded.";
  } catch (error) {
    console.log("error", error);
    return error instanceof Error && error.message.length > 0
      ? error.message
      : "Error, please try again.";
  }
};

pnpm db:generate
pnpm db:migrate

请使用 vercel ai sdk 重构 @app/api/openai/embedding.ts 中的代码，保存到@app/api/vercelai/embedding.ts 下

import { env } from "@/lib/env.mjs";
import { embed, embedMany } from "ai";
import { findSimilarContent } from "@/lib/db/vercelai/selector";
import { model } from "./settings";

const embeddingModel = model.embedding(env.EMBEDDING);

const generateChunks = (input: string): string[] => {
  return input
    .trim()
    .split("-------split line-------")
    .filter((chunk) => chunk !== "");
};

/**
 * 生成嵌入向量
 * @param value 输入文本
 * @returns 嵌入向量
 */
export const generateEmbeddings = async (
  value: string,
): Promise<Array<{ embedding: number[]; content: string }>> => {
  const chunks = generateChunks(value);

  // 使用 AI SDK 的 embedMany 函数来批量生成 embeddings
  const { embeddings } = await embedMany({
    model: embeddingModel,
    values: chunks,
  });

  return embeddings.map((embedding, i) => ({
    content: chunks[i],
    embedding,
  }));
};

/**
 * 生成单个嵌入向量
 * @param value 输入文本
 * @returns 嵌入向量
 */
export const generateEmbedding = async (value: string): Promise<number[]> => {
  const input = value.replaceAll("\\n", " ");

  // 使用 AI SDK 的 embed 函数来生成单个 embedding
  const { embedding } = await embed({
    model: embeddingModel,
    value: input,
  });

  return embedding;
};

/**
 * 查找相关内容
 * @param userQuery 用户查询
 * @returns 相关内容
 */
export const findRelevantContent = async (
  userQuery: string,
): Promise<{ content: string; similarity: number }[]> => {
  const userQueryEmbedded = await generateEmbedding(userQuery);
  return findSimilarContent(userQueryEmbedded);
};

import fs from "fs";
import { env } from "@/lib/env.mjs";
import { createResource } from "@/lib/db/vercelai/actions";
import { generateEmbeddings } from "./embedding";

console.log("env.EMBEDDING", env.EMBEDDING);

/**
 * 入库
 */
export const generateEmbeddingsFromDocs = async () => {
  console.log("start reading docs");
  /**
   * 读取文档
   */
  const docs = fs.readFileSync("./ai-docs/basic-components.txt", "utf8");

  console.log("start generating embeddings");
  /**
   * 生成嵌入向量
   */
  const embeddings = await generateEmbeddings(docs);

  console.log("start creating resource");
  /**
   * 创建资源，插入到数据库表
   */
  await createResource(embeddings);

  console.log("success~~~");
};

generateEmbeddingsFromDocs();