> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 크로마 벡터 스토어

ChromaVector 클래스는 다음을 사용하여 벡터 검색을 제공합니다.[Chroma](https://docs.trychroma.com/docs/overview/getting-started), 오픈 소스 임베딩 데이터베이스입니다. 메타데이터 필터링 및 하이브리드 검색 기능을 통해 효율적인 벡터 검색을 제공합니다.

> **정보:**
>
> **크로마 클라우드**
>
> Chroma Cloud는 서버리스 벡터 및 전체 텍스트 검색을 지원합니다. 매우 빠르고 비용 효율적이며 고용량이며 통증이 없습니다. DB를 만들고 $5의 무료 크레딧으로 30초 안에 사용해 보세요.
>
> [Chroma 클라우드 시작하기](https://trychroma.com/signup)

## 생성자 옵션

**host** (`string`): Chroma 서버의 호스트 주소입니다. 기본값은 'localhost'입니다.

**port** (`number`): Chroma 서버의 포트 번호입니다. 기본값은 8000입니다.

**ssl** (`boolean`): 연결에 SSL/HTTPS를 사용할지 여부입니다. 기본값은 false입니다.

**apiKey** (`string`): Chroma Cloud API 키입니다.

**tenant** (`string`): 연결할 Chroma 서버의 테넌트 이름입니다. 단일 노드 Chroma의 기본값은 'default\_tenant'입니다. Chroma Cloud 사용자는 제공된 API 키를 기반으로 자동 확인됩니다.

**database** (`string`): 연결할 데이터베이스 이름입니다. 단일 노드 Chroma의 기본값은 'default\_database'입니다. Chroma Cloud 사용자는 제공된 API 키를 기반으로 자동 확인됩니다.

**headers** (`Record<string, any>`): 요청과 함께 전송할 추가 HTTP 헤더입니다.

**fetchOptions** (`RequestInit`): HTTP 요청을 위한 추가 fetch 옵션입니다.

## Chroma 서버 실행

Chroma Cloud 사용자는 `ChromaVector` 생성자에 API 키, 테넌트, 데이터베이스 이름을 제공하세요. `@mastra/chroma` 패키지를 설치하면 [Chroma CLI](https://docs.trychroma.com/docs/cli/db)를 사용할 수 있으며, `chroma db connect [DB-NAME] --env-file` 명령으로 이러한 값을 환경 변수로 설정할 수 있습니다. 그렇지 않은 경우 단일 노드 Chroma 서버를 설정하기 위한 몇 가지 옵션이 있습니다.

- Chroma CLI를 사용해 로컬에서 실행합니다: `chroma run`. 더 많은 구성 옵션은 [Chroma 문서](https://docs.trychroma.com/docs/cli/run)에서 확인할 수 있습니다.
- 공식 Chroma 이미지를 사용하여 [Docker](https://docs.trychroma.com/guides/deploy/docker)에서 실행합니다.
- 선택한 Provider에 자체 Chroma 서버를 배포합니다. Chroma는 [AWS](https://docs.trychroma.com/guides/deploy/aws), [Azure](https://docs.trychroma.com/guides/deploy/azure), [GCP](https://docs.trychroma.com/guides/deploy/gcp)용 예제 템플릿을 제공합니다.

## 행동 양식

### `createIndex()`

**indexName** (`string`): 생성할 인덱스의 이름입니다.

**dimension** (`number`): 벡터 차원입니다(사용 중인 임베딩 Model과 일치해야 함).

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색을 위한 거리 측정 방식입니다. (Default: `cosine`)

### `forkIndex()`

참고: 분기는 Chroma Cloud에서만 지원되거나 자체 OSS를 배포하는 경우에만 지원됩니다.**distributed** Chroma.

`forkIndex`기존 Chroma 인덱스를 즉시 포크할 수 있습니다. 분기된 인덱스에 대한 작업은 원본 인덱스에 영향을 주지 않습니다. 자세히 알아보기[Chroma docs](https://docs.trychroma.com/cloud/collection-forking).

**indexName** (`string`): 포크할 인덱스의 이름입니다.

**newIndexName** (`string`): 포크된 인덱스의 이름입니다.

### `upsert()`

**indexName** (`string`): 업서트할 인덱스의 이름입니다.

**vectors** (`number[][]`): 임베딩 벡터 배열입니다.

**metadata** (`Record<string, any>[]`): 각 벡터의 메타데이터입니다.

**ids** (`string[]`): 선택적 벡터 ID입니다(제공하지 않으면 자동 생성됨).

**documents** (`string[]`): Chroma 전용: 벡터와 연결된 원본 텍스트 문서입니다.

### `query()`

`queryVector`를 사용하여 인덱스를 쿼리합니다. `queryVector`와의 거리순으로 의미상 유사한 레코드 배열을 반환합니다. 각 레코드는 다음 형태입니다.

```typescript
{
  id: string;
  score: number;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

타입 추론을 위해 메타데이터의 형태를 `query` 호출에 전달하세요: `query<T>()`.

**indexName** (`string`): 쿼리할 인덱스의 이름입니다.

**queryVector** (`number[]`): 유사한 벡터를 찾기 위한 쿼리 벡터입니다.

**topK** (`number`): 반환할 결과 수입니다. (Default: `10`)

**filter** (`Record<string, any>`): 쿼리에 적용할 메타데이터 필터입니다.

**includeVector** (`boolean`): 결과에 벡터를 포함할지 여부입니다. (Default: `false`)

**documentFilter** (`Record<string, any>`): Chroma 전용: 문서 콘텐츠에 적용할 필터입니다.

### `get()`

ID, 메타데이터 및 문서 필터를 통해 Chroma 색인에서 기록을 가져옵니다. 모양의 레코드 배열을 반환합니다.

```typescript
{
  id: string;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}
```

타입 추론을 위해 메타데이터의 형태를 `get` 호출에 전달하세요: `get<T>()`.

**indexName** (`string`): 쿼리할 인덱스의 이름입니다.

**ids** (`string[]`): 반환할 레코드 ID 목록입니다. 제공하지 않으면 모든 레코드를 반환합니다.

**filter** (`Record<string, any>`): 메타데이터 필터입니다.

**includeVector** (`boolean`): 결과에 벡터를 포함할지 여부입니다. (Default: `false`)

**documentFilter** (`Record<string, any>`): Chroma 전용: 문서 콘텐츠에 적용할 필터입니다.

**limit** (`number`): 반환할 최대 레코드 수입니다. (Default: `100`)

**offset** (`number`): 레코드 반환을 시작할 오프셋입니다. 결과 페이지를 나누려면 limit과 함께 사용하세요.

### `listIndexes()`

인덱스 이름의 배열을 문자열로 반환합니다.

### `describeIndex()`

**indexName** (`string`): 설명을 조회할 인덱스의 이름입니다.

보고:

```typescript
interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}
```

### `deleteIndex()`

**indexName** (`string`): 삭제할 인덱스의 이름입니다.

### `updateVector()`

ID 또는 메타데이터 필터를 기준으로 단일 벡터를 업데이트합니다. `id`와 `filter` 중 하나만 제공해야 합니다.

**indexName** (`string`): 업데이트할 벡터가 포함된 인덱스의 이름입니다.

**id** (`string`): 업데이트할 벡터의 ID입니다(filter와 함께 사용할 수 없음).

**filter** (`Record<string, any>`): 업데이트할 벡터를 식별하는 메타데이터 필터입니다(id와 함께 사용할 수 없음).

**update** (`object`): 업데이트 매개변수입니다.

`update` 객체에는 다음 항목이 포함될 수 있습니다.

**vector** (`number[]`): 기존 벡터를 대체할 새 벡터입니다.

**metadata** (`Record<string, any>`): 기존 메타데이터를 대체할 새 메타데이터입니다.

예:

```typescript
// Update by ID
await vectorStore.updateVector({
  indexName: 'docs',
  id: 'vec_123',
  update: { metadata: { status: 'reviewed' } },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
  update: { metadata: { version: 2 } },
})
```

### `deleteVector()`

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름입니다.

**id** (`string`): 삭제할 벡터의 ID입니다.

### `deleteVectors()`

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. 이 메서드는 대량 삭제 및 소스 기반 벡터 관리를 지원합니다. `ids`와 `filter` 중 하나만 제공해야 합니다.

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름입니다.

**ids** (`string[]`): 삭제할 벡터 ID 배열입니다(filter와 함께 사용할 수 없음).

**filter** (`Record<string, any>`): 삭제할 벡터를 식별하는 메타데이터 필터입니다(ids와 함께 사용할 수 없음).

예:

```typescript
// Delete all chunks from a document
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
})

// Delete multiple vectors by ID
await vectorStore.deleteVectors({
  indexName: 'docs',
  ids: ['vec_1', 'vec_2', 'vec_3'],
})

// Delete old temporary documents
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: {
    $and: [{ bucket: 'temp' }, { indexed_at: { $lt: '2025-01-01' } }],
  },
})
```

## 응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

```typescript
interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  document?: string // Chroma-specific: Original document if it was stored
  vector?: number[] // Only included if includeVector is true
}
```

## 오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

```typescript
try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}
```

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)