加入Orama的Slack频道

如果您需要更多信息、帮助或想提供有关Orama的一般反馈，请加入 Orama Slack频道

主要特性

安装

您可以使用npm、yarn、pnpm或bun安装Orama：

npm i @orama/orama

或者直接在浏览器模块中导入：

<html>
  <body>
    <script type="module">
      import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'

      // ...
    </script>
  </body>
</html>

使用Deno时，您可以使用相同的CDN URL或使用npm说明符：

import { create, search, insert } from 'npm:@orama/orama'

完整文档请访问https://docs.askorama.ai。

使用方法

Orama使用起来相当简单。首先需要创建一个新的数据库实例并设置索引模式：

import { create, insert, remove, search, searchVector } from '@orama/orama'

const db = await create({
  schema: {
    name: 'string',
    description: 'string',
    price: 'number',
    embedding: 'vector[1536]', // 向量大小必须在模式初始化时指定
    meta: {
      rating: 'number',
    },
  },
})

Orama目前支持10种不同的数据类型：

类型	描述	示例
`string`	字符串	`'Hello world'`
`number`	数值，可以是浮点数或整数	`42`
`boolean`	布尔值	`true`
`enum`	枚举值	`'drama'`
`geopoint`	地理坐标点	`{ lat: 40.7128, lon: 74.0060 }`
`string[]`	字符串数组	`['red', 'green', 'blue']`
`number[]`	数值数组	`[42, 91, 28.5]`
`boolean[]`	布尔值数组	`[true, false, false]`
`enum[]`	枚举值数组	`['comedy', 'action', 'romance']`
`vector[<size>]`	用于执行向量搜索的数值向量	`[0.403, 0.192, 0.830]`

Orama只会索引模式中指定的属性，但允许您在需要时设置和存储额外的数据。

创建数据库实例后，您可以开始添加一些文档：

await insert(db, {
  name: '无线耳机',
  description: '体验这款噪音消除无线耳机带来的身临其境的音质。',
  price: 99.99,
  embedding: [...],
  meta: {
    rating: 4.5,
  },
})

await insert(db, {
  name: '智能LED灯泡',
  description: '使用这款节能智能LED灯泡控制家中的照明，兼容大多数智能家居系统。',
  price: 24.99,
  embedding: [...],
  meta: {
    rating: 4.3,
  },
})

await insert(db, {
  name: '便携式充电器',
  description: '使用这款小巧快速充电的便携式充电器，在外出时永不断电。',
  price: 29.99,
  embedding: [...],
  meta: {
    rating: 3.6,
  },
})

插入数据后，您就可以开始查询数据库了。

const searchResult = await search(db, {
  term: '耳机',
})

在上面的例子中，您将搜索所有包含"耳机"一词的文档，查找模式中指定的每个string属性：

{
  elapsed: {
    raw: 99512,
    formatted: '99μs',
  },
  hits: [
    {
      id: '41013877-56',
      score: 0.925085832971998432,
      document: {
        name: '无线耳机',
        description: '体验这款噪音消除无线耳机带来的身临其境的音质。',
        price: 99.99,
        meta: {
          rating: 4.5
        }
      }
    }
  ],
  count: 1
}

您还可以将查找限制在特定属性上：

const searchResult = await search(db, {
  term: '身临其境的音质',
  properties: ['description'],
})

结果：

{
  elapsed: {
    raw: 21492,
    formatted: '21μs',
  },
  hits: [
    {
      id: '41013877-56',
      score: 0.925085832971998432,
      document: {
        name: '无线耳机',
        description: '体验这款噪音消除无线耳机带来的身临其境的音质。',
        price: 99.99,
        meta: {
          rating: 4.5
        }
      }
    }
  ],
  count: 1
}

您可以使用非字符串数据来过滤、分组和创建分面：

const searchResult = await search(db, {
  term: '身临其境的音质',
  where: {
    price: {
      lte: 199.99
    },
    rating: {
      gt: 4
    }
  },
})

执行混合和向量搜索

Orama是一个全文和向量搜索引擎。这使您可以根据特定用例采用不同的搜索范式。

要执行向量或混合搜索，您可以使用与全文搜索相同的search方法。

您只需指定要执行向量搜索的属性，以及用于执行向量相似度的向量：

const searchResult = await searchVector(db, {
  mode: 'vector', // 或 'hybrid'
  vector: {
    value: [...], // 用作输入的OpenAI嵌入或类似向量
    property: 'embedding' // 要搜索的属性。向量搜索时必填
  }
})

如果你正在使用Orama安全AI代理（强烈推荐），你可以在搜索时跳过向量配置，因为官方的Orama安全AI代理插件会自动为你处理：

import { create } from '@orama/orama'
import { pluginSecureProxy } from '@orama/plugin-secure-proxy'

const secureProxy = secureProxyPlugin({
  apiKey: '<你的公共API密钥>',
  defaultProperty: 'embedding', // 执行向量和混合搜索的默认属性
  model: 'openai/text-embedding-ada-002' // 用于生成嵌入的模型
})

const db = await create({
  schema: {
    name: 'string',
    description: 'string',
    price: 'number',
    embedding: 'vector[1536]',
    meta: {
      rating: 'number',
    },
  },
  plugins: [secureProxy]
})

const resultsHybrid = await search(db, {
  mode: 'vector', // 或 'hybrid'
  term: '适合对冰淇淋充满热情的小孩子的电子游戏',
  where: {
    price: {
      lte: 19.99
    },
    'meta.rating': {
      gte: 4.5
    }
  }
})

执行地理搜索

Orama支持将地理搜索作为搜索过滤器。它将搜索通过schema中指定为geopoint的所有属性：

import { create, insert } from '@orama/orama'

const db = await create({
  schema: {
    name: 'string',
    location: 'geopoint'
  }
})

await insert(db, { name: '米兰大教堂', location: { lat: 45.46409, lon: 9.19192 } })
await insert(db, { name: '大教堂广场', location: { lat: 45.46416, lon: 9.18945 } })
await insert(db, { name: '皇家小广场', location: { lat: 45.46339, lon: 9.19092 } })

const searchResult = await search(db, {
  term: '大教堂',
  where: {
    location: {           // 我们想要过滤的属性
      radius: {           // 我们想要应用的过滤器（在这种情况下："radius"）
        coordinates: {    // 中心坐标
          lat: 45.4648, 
          lon: 9.18998
        },
        unit: 'm',        // 测量单位。默认为"m"（米）
        value: 1000,      // 半径长度。在这种情况下，1公里
        inside: true      // 我们是否想返回半径内或半径外的文档。默认为"true"
      }
    }
  }
})

Orama地理搜索API支持基于距离的搜索（通过radius）或基于多边形的搜索（通过polygon）。

默认情况下，Orama将使用Haversine公式来执行地理搜索，但可以通过在radius或polygon配置中传递highPrecision选项来启用高精度搜索。这将告诉Orama使用Vicenty公式，它对于更长距离的计算更精确。

在官方文档中阅读更多内容。