同义词管理 #

什么是同义词？ #

同义词让不同的搜索词能够匹配相同的结果，提升搜索体验。

text

用户搜索: "手机"
匹配结果: 包含"手机"或"电话"或"移动电话"的记录

同义词类型 #

1. 普通同义词（Synonym） #

双向等价，所有词互为同义词：

javascript

{
  "objectID": "synonym-1",
  "type": "synonym",
  "synonyms": ["手机", "电话", "移动电话", "cellphone"]
}

// 搜索"手机" → 匹配包含"电话"的记录
// 搜索"电话" → 匹配包含"手机"的记录

2. 单向同义词（One-way Synonym） #

单向映射，输入词映射到同义词：

javascript

{
  "objectID": "oneway-1",
  "type": "oneWaySynonym",
  "input": "苹果",
  "synonyms": ["Apple", "iPhone", "iPad"]
}

// 搜索"苹果" → 匹配包含"Apple"、"iPhone"、"iPad"的记录
// 搜索"iPhone" → 不匹配"苹果"

3. 替代修正（Alternative Correction） #

带容错的替代词：

javascript

{
  "objectID": "alt-1",
  "type": "altCorrection1",
  "word": "手机",
  "corrections": ["电话"]
}

// altCorrection1: 允许1个拼写错误
// altCorrection2: 六许2个拼写错误

4. 占位符（Placeholder） #

可替换的占位符：

javascript

{
  "objectID": "placeholder-1",
  "type": "placeholder",
  "placeholder": "<city>",
  "replacements": ["北京", "上海", "广州", "深圳"]
}

// 搜索"北京酒店" → 匹配"<city>酒店"

添加同义词 #

通过Dashboard #

进入索引页面
点击"Synonyms"标签
点击"Add Synonym"
选择类型并填写内容

通过API #

javascript

const index = client.initIndex('products');

// 添加单个同义词
await index.saveSynonym({
  objectID: 'synonym-1',
  type: 'synonym',
  synonyms: ['手机', '电话', '移动电话']
});

// 批量添加同义词
await index.saveSynonyms([
  {
    objectID: 'synonym-1',
    type: 'synonym',
    synonyms: ['手机', '电话', '移动电话']
  },
  {
    objectID: 'synonym-2',
    type: 'synonym',
    synonyms: ['笔记本', '笔记本电脑', 'laptop']
  },
  {
    objectID: 'oneway-1',
    type: 'oneWaySynonym',
    input: '苹果',
    synonyms: ['Apple', 'iPhone', 'iPad', 'MacBook']
  }
]);

同义词配置示例 #

电商场景 #

javascript

const ecommerceSynonyms = [
  // 品牌同义词
  {
    objectID: 'brand-apple',
    type: 'oneWaySynonym',
    input: '苹果',
    synonyms: ['Apple', 'iPhone', 'iPad', 'MacBook', 'AirPods']
  },
  {
    objectID: 'brand-samsung',
    type: 'oneWaySynonym',
    input: '三星',
    synonyms: ['Samsung', 'Galaxy']
  },
  
  // 产品类型同义词
  {
    objectID: 'type-phone',
    type: 'synonym',
    synonyms: ['手机', '电话', '移动电话', 'smartphone']
  },
  {
    objectID: 'type-laptop',
    type: 'synonym',
    synonyms: ['笔记本', '笔记本电脑', 'laptop', 'notebook']
  },
  {
    objectID: 'type-headphone',
    type: 'synonym',
    synonyms: ['耳机', '耳麦', 'headphone', 'earphone']
  },
  
  // 功能同义词
  {
    objectID: 'feature-wireless',
    type: 'synonym',
    synonyms: ['无线', '蓝牙', 'wireless', 'bluetooth']
  }
];

await index.saveSynonyms(ecommerceSynonyms);

内容场景 #

javascript

const contentSynonyms = [
  // 主题同义词
  {
    objectID: 'topic-ai',
    type: 'synonym',
    synonyms: ['人工智能', 'AI', '机器学习', '深度学习']
  },
  {
    objectID: 'topic-web',
    type: 'synonym',
    synonyms: ['前端', 'Web', '网页', '网站']
  },
  
  // 编程语言同义词
  {
    objectID: 'lang-js',
    type: 'synonym',
    synonyms: ['JavaScript', 'JS', 'ECMAScript']
  },
  {
    objectID: 'lang-py',
    type: 'synonym',
    synonyms: ['Python', 'python', 'py']
  }
];

await index.saveSynonyms(contentSynonyms);

管理同义词 #

获取同义词 #

javascript

// 获取单个同义词
const synonym = await index.getSynonym('synonym-1');

// 获取所有同义词
const { hits } = await index.searchSynonyms('');

更新同义词 #

javascript

await index.saveSynonym({
  objectID: 'synonym-1',
  type: 'synonym',
  synonyms: ['手机', '电话', '移动电话', 'cellphone', 'smartphone']
});

删除同义词 #

javascript

// 删除单个同义词
await index.deleteSynonym('synonym-1');

// 清空所有同义词
await index.clearSynonyms();

同义词搜索 #

启用同义词搜索 #

javascript

// 默认启用
const results = await index.search('手机');

// 禁用同义词
const results = await index.search('手机', {
  synonyms: false
});

同义词高亮 #

javascript

// 同义词匹配的结果也会高亮
const results = await index.search('手机', {
  attributesToHighlight: ['name', 'description']
});

// 搜索"手机"时，"电话"也会被高亮

高级配置 #

同义词优先级 #

javascript

// 同义词不会影响排名，只影响匹配
// 排名仍基于原始查询词

同义词与拼写容错 #

javascript

// 同义词在拼写容错之前处理
// 搜索"iphne" → 拼写修正为"iphone" → 同义词扩展为"苹果"

限制同义词数量 #

javascript

// 建议每个索引的同义词数量不超过10000条
// 过多同义词会影响性能

同义词最佳实践 #

1. 使用单向同义词 #

javascript

// ✅ 推荐：使用单向同义词避免歧义
{
  type: 'oneWaySynonym',
  input: '苹果',
  synonyms: ['Apple', 'iPhone']
}

// ❌ 避免：双向同义词可能造成意外匹配
{
  type: 'synonym',
  synonyms: ['苹果', 'Apple']  // "Apple"也会匹配"苹果"
}

2. 避免过度扩展 #

javascript

// ❌ 避免：过多同义词
{
  synonyms: ['手机', '电话', '移动电话', 'cellphone', 'smartphone', 
             'telephone', 'mobile', 'handphone', '通讯设备']
}

// ✅ 推荐：精选核心同义词
{
  synonyms: ['手机', '电话', '移动电话']
}

3. 定期审查 #

javascript

// 通过分析无结果搜索来发现需要的同义词
async function findMissingSynonyms() {
  const analytics = await client.getAnalytics();
  const noResultSearches = analytics.searches.filter(s => s.count === 0);
  
  // 分析这些搜索词，判断是否需要添加同义词
}

4. 使用占位符 #

javascript

// 对于可变部分使用占位符
{
  type: 'placeholder',
  placeholder: '<color>',
  replacements: ['红色', '蓝色', '绿色', '黑色', '白色']
}

// 搜索"红色手机" → 匹配"<color>手机"

同义词工具 #

同义词管理类 #

javascript

class SynonymManager {
  constructor(index) {
    this.index = index;
  }
  
  async addSynonyms(synonyms) {
    const formatted = synonyms.map(s => ({
      objectID: s.id,
      type: s.type || 'synonym',
      synonyms: s.synonyms,
      ...(s.input && { input: s.input })
    }));
    
    await this.index.saveSynonyms(formatted);
  }
  
  async listSynonyms() {
    const { hits } = await this.index.searchSynonyms('');
    return hits;
  }
  
  async findSynonym(word) {
    const { hits } = await this.index.searchSynonyms(word);
    return hits.find(s => 
      s.synonyms?.includes(word) || s.input === word
    );
  }
  
  async removeSynonym(id) {
    await this.index.deleteSynonym(id);
  }
  
  async importFromCSV(csvContent) {
    const lines = csvContent.split('\n');
    const synonyms = [];
    
    for (const line of lines) {
      const words = line.split(',').map(w => w.trim());
      if (words.length >= 2) {
        synonyms.push({
          objectID: `synonym-${Date.now()}-${Math.random()}`,
          type: 'synonym',
          synonyms: words
        });
      }
    }
    
    await this.index.saveSynonyms(synonyms);
  }
  
  async exportToCSV() {
    const { hits } = await this.index.searchSynonyms('');
    return hits
      .filter(s => s.type === 'synonym')
      .map(s => s.synonyms.join(','))
      .join('\n');
  }
}

使用示例 #

javascript

const manager = new SynonymManager(index);

// 添加同义词
await manager.addSynonyms([
  { id: 'syn-1', synonyms: ['手机', '电话'] },
  { id: 'syn-2', type: 'oneWaySynonym', input: '苹果', synonyms: ['Apple'] }
]);

// 列出所有同义词
const allSynonyms = await manager.listSynonyms();

// 查找特定词的同义词
const synonym = await manager.findSynonym('手机');

// 导出为CSV
const csv = await manager.exportToCSV();

同义词示例 #

完整电商同义词配置 #

javascript

const fullEcommerceSynonyms = [
  // 品牌中英文映射
  { objectID: 'brand-1', type: 'oneWaySynonym', input: '苹果', synonyms: ['Apple'] },
  { objectID: 'brand-2', type: 'oneWaySynonym', input: '三星', synonyms: ['Samsung'] },
  { objectID: 'brand-3', type: 'oneWaySynonym', input: '华为', synonyms: ['Huawei'] },
  { objectID: 'brand-4', type: 'oneWaySynonym', input: '小米', synonyms: ['Xiaomi', 'MI'] },
  { objectID: 'brand-5', type: 'oneWaySynonym', input: '联想', synonyms: ['Lenovo'] },
  
  // 产品类型
  { objectID: 'type-1', type: 'synonym', synonyms: ['手机', '电话', '移动电话'] },
  { objectID: 'type-2', type: 'synonym', synonyms: ['电脑', '计算机', 'PC'] },
  { objectID: 'type-3', type: 'synonym', synonyms: ['笔记本', '笔记本电脑', 'laptop'] },
  { objectID: 'type-4', type: 'synonym', synonyms: ['平板', '平板电脑', 'tablet'] },
  { objectID: 'type-5', type: 'synonym', synonyms: ['耳机', '耳麦', 'headphone'] },
  
  // 功能特性
  { objectID: 'feature-1', type: 'synonym', synonyms: ['无线', '蓝牙', 'wireless'] },
  { objectID: 'feature-2', type: 'synonym', synonyms: ['触屏', '触摸屏', 'touchscreen'] },
  { objectID: 'feature-3', type: 'synonym', synonyms: ['防水', '防泼溅', 'waterproof'] },
  
  // 常见拼写错误
  { objectID: 'typo-1', type: 'altCorrection1', word: 'iPhone', corrections: ['iphone'] },
  { objectID: 'typo-2', type: 'altCorrection1', word: 'Samsung', corrections: ['samsung'] }
];

await index.saveSynonyms(fullEcommerceSynonyms);

总结 #

同义词管理要点：

要点	说明
类型	synonym, oneWaySynonym, altCorrection, placeholder
添加	saveSynonym, saveSynonyms
管理	getSynonym, deleteSynonym, clearSynonyms
最佳实践	使用单向同义词、避免过度扩展、定期审查

接下来，让我们学习自定义排名。