AI导哈

设计系统向量嵌入工具

一个Node.js应用程序，将Phenom设计系统组件嵌入ChromaDB中，支持语义搜索和检索，使开发者能够通过自然语言查询找到相关组件。

  • by Deepali967
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Deepali967/ds-mcp

使用说明

Phenom设计系统矢量嵌入

一个Node.js应用程序，将Phenom设计系统组件嵌入ChromaDB进行语义搜索和检索。这使开发人员能够使用自然语言查询找到相关组件。

🚀 特性

  • 语义搜索：使用自然语言查询查找组件
  • 本地矢量数据库：使用ChromaDB进行本地持久存储
  • 交互式搜索：用于探索组件的命令行界面
  • 类别浏览：按类别浏览组件
  • 综合元数据：存储组件详细信息、使用示例和可访问性信息
  • 质量检测：内置测试以验证嵌入质量

📋 先决条件

  • Node.js 18.0.0或更高版本
  • OpenAI API密钥（用于生成嵌入）
  • 可选：ChromaDB服务器（如果不可用，将使用嵌入式模式）

🛠️ 安装

  1. 克隆或下载项目文件

  2. 安装依赖项:

    npm install

  3. 设置环境变量:

    cp env.example .env

    编辑 .env 并添加您的OpenAI API密钥：

    OPENAI_API_KEY=your_openai_api_key_here

🎯 用法

步骤1：嵌入组件

首先，将飞鸿设计系统组件嵌入ChromaDB：

npm start
# or
node embed-components.js

这将：

  • 从以下位置加载组件数据 phenom-ds-complete-vector-embeddings.json
  • 使用OpenAI的文本嵌入3-small模型生成嵌入
  • 将它们存储在ChromaDB中（创建 ./chroma_db 目录）
  • 运行测试查询以验证设置

第二步：搜索组件

嵌入后，您可以搜索组件：

# Interactive search mode
npm run search
# or
node search-components.js

# Quick search with query
node search-components.js "button component for forms"

# Show example queries
node search-components.js --examples

# Show help
node search-components.js --help

步骤3：测试嵌入质量

验证嵌入是否正常工作：

npm test
# or
node test-embeddings.js

🔍 搜索示例

以下是一些您可以尝试的示例查询：

  • "button component for forms"
  • "data table with sorting"
  • "modal dialog for confirmations"
  • "input field with validation"
  • "navigation menu"
  • "loading spinner"
  • "user avatar"
  • "dropdown selection"
  • "date picker calendar"
  • "toast notifications"

📁 项目结构

ds-mcp/
├── embed-components.js          # Main embedding script
├── search-components.js         # Search interface
├── test-embeddings.js          # Quality testing
├── package.json                # Dependencies and scripts
├── env.example                 # Environment variables template
├── phenom-ds-complete-vector-embeddings.json  # Component data
├── chroma_db/                  # ChromaDB storage (created after embedding)
└── README.md                   # This file

⚙️ 配置

环境变量

变量 描述 默认值
OPENAI_API_KEY OpenAI API密钥（必需） -
CHROMA_HOST ChromaDB服务器主机 localhost
CHROMA_PORT ChromaDB服务器端口 8000
CHROMA_COLLECTION_NAME 收藏名称 phenom-ds-components
EMBEDDING_MODEL OpenAI嵌入模型 text-embedding-3-small
CHROMA_PERSIST_PATH 本地存储路径 ./chroma_db

ChromaDB设置选项

选项1：嵌入式模式（默认）

  • 无需额外设置
  • 数据存储在本地 ./chroma_db
  • 如果没有运行ChromaDB服务器，则自动使用

选项2:ChromaDB服务器

  • 安装ChromaDB服务器： pip install chromadb
  • 启动服务器： chroma run --host localhost --port 8000
  • 应用程序将自动检测并使用服务器

🧪 测试

测试套件通过运行预定义的查询并检查结果中是否找到预期的组件来验证嵌入质量。

node test-embeddings.js

测试包括：

  • 质量测试：验证语义搜索是否返回相关组件
  • 类别测试：确保特定类别的搜索正常工作
  • 性能指标：显示成功率和相关性得分

📊 组件数据结构

矢量数据库中的每个组件包括：

  • 基本信息：名称、标题、类别、类型
  • 内容：描述、使用指南、关键字
  • 技术性的：选择器、模块、道具、事件
  • 例子：代码示例，Figma网址
  • 无障碍：WCAG合规信息
  • 元数据：语义标签、实现细节

🔧 故障排除

常见问题

  1. “未找到集合”错误

    • 跑 node embed-components.js 首先创建集合

  2. OpenAI API错误

    • 检查API密钥 .env
    • 确保您有足够的API信用
    • 验证嵌入模型是否可用

  3. ChromaDB连接问题

    • 应用程序将自动回退到嵌入式模式
    • 如果使用服务器模式，请检查ChromaDB服务器是否正在运行

  4. 空搜索结果

    • 验证嵌入过程是否成功完成
    • 尝试不同的搜索词
    • 检查测试套件以进行验证

性能提示

  • 批处理：成分分批处理，以遵守API速率限制
  • 缓存：ChromaDB提供持久存储，除非数据发生变化，否则不需要重新嵌入
  • 模型选择: text-embedding-3-small 提供了质量和速度的良好平衡

🤝 贡献

要添加新组件或修改嵌入过程，请执行以下操作：

  1. 更新 phenom-ds-complete-vector-embeddings.json 使用新组件数据
  2. 跑 node embed-components.js 重新嵌入
  3. 测试用 node test-embeddings.js
  4. 如果需要，更新测试用例

📝 许可证

MIT许可证-有关详细信息，请参阅代码文件。

🆘 支持

对于问题或疑问：

  1. 检查上面的故障排除部分
  2. 验证您的环境设置是否符合先决条件
  3. 使用提供的示例查询进行测试
  4. 检查ChromaDB和OpenAI服务状态

搜索愉快！ 🎉

相关 MCP