Google Cloud SQL for PostgreSQL 통합

Google Cloud SQL for PostgreSQL 통합

LangChain JavaScript로 Google Cloud SQL for PostgreSQL 벡터 스토어와 통합해요.

Cloud SQL은 높은 성능, 원활한 통합, 뛰어난 확장성을 제공하고 PostgreSQL 같은 데이터베이스 엔진을 제공하는 완전 관리형 관계형 데이터베이스 서비스예요.

이 가이드는 PostgresVectorStore 클래스를 사용해 Cloud SQL for PostgreSQL로 벡터 임베딩을 저장하는 방법을 간략히 소개해요.

개요 (Overview)

통합 세부 정보 (Integration details)

클래스 패키지 PY 지원 버전
PostgresVectorStore @langchain/google-cloud-sql-pg ✅ NPM - Version

시작 전에 (Before you begin)

이 패키지를 사용하려면 먼저 다음 단계를 거쳐야 해요:

  1. Cloud Platform 프로젝트를 선택하거나 만드세요.
  2. 프로젝트에 결제를 활성화하세요.
  3. Cloud SQL Admin API를 활성화하세요.
  4. 인증을 설정하세요.
  5. CloudSQL 인스턴스를 만드세요.
  6. CloudSQL 데이터베이스를 만드세요.
  7. 데이터베이스에 사용자를 추가하세요.

인증 (Authentication)

gcloud auth login 명령으로 Google Cloud 계정에 로컬 인증하세요.

Google Cloud 프로젝트 설정 (Set your Google cloud project)

로컬에서 Google Cloud 리소스를 활용하도록 Google Cloud 프로젝트 ID를 설정하세요:

gcloud config set project YOUR-PROJECT-ID

프로젝트 ID를 모른다면 다음을 시도하세요:

PostgresVectorStore 인스턴스 설정

PostgresVectorStore 라이브러리를 사용하려면 @langchain/google-cloud-sql-pg 패키지를 설치하고 아래 단계를 따라야 해요.

```bash npm npm install @langchain/google-cloud-sql-pg @langchain/core ``` 
yarn add @langchain/google-cloud-sql-pg @langchain/core

pnpm add @langchain/google-cloud-sql-pg @langchain/core

먼저 Google Cloud 계정에 로그인하고 Google Cloud 프로젝트에 기반해 다음 환경 변수를 설정해야 해요. 이 값은 PostgresEngine 인스턴스를 어떻게 구성하는지(fromInstance, fromEngine, fromEngineArgs)에 따라 정의돼요:

PROJECT_ID="your-project-id"
REGION="your-project-region" // example: "us-central1"
INSTANCE_NAME="your-instance"
DB_NAME="your-database-name"
DB_USER="your-database-user"
PASSWORD="your-database-password"

인스턴스 설정 (Setting up an instance)

PostgresVectorStore를 인스턴스화하려면 먼저 PostgresEngine으로 데이터베이스 연결을 만들고, 벡터 스토어 테이블을 초기화한 뒤 마지막으로 .initialize() 메서드를 호출해 벡터 스토어를 인스턴스화해야 해요.

import {
  Column,
  PostgresEngine,
  PostgresEngineArgs,
  PostgresVectorStore,
  PostgresVectorStoreArgs,
  VectorStoreTableArgs,
} from "@langchain/google-cloud-sql-pg";
import { SyntheticEmbeddings } from "@langchain/core/utils/testing"; // This is used as an Embedding service
import * as dotenv from "dotenv";

dotenv.config();

const peArgs: PostgresEngineArgs = {
  user: process.env.DB_USER ?? "",
  password: process.env.PASSWORD ?? "",
};

// PostgresEngine instantiation
const engine: PostgresEngine = await PostgresEngine.fromInstance(
  process.env.PROJECT_ID ?? "",
  process.env.REGION ?? "",
  process.env.INSTANCE_NAME ?? "",
  process.env.DB_NAME ?? "",
  peArgs
);

const vectorStoreArgs: VectorStoreTableArgs = {
  metadataColumns: [new Column("page", "TEXT"), new Column("source", "TEXT")],
};

// Vector store table initialization
await engine.initVectorstoreTable("my_vector_store_table", 768, vectorStoreArgs);
const embeddingService = new SyntheticEmbeddings({ vectorSize: 768 });

const pvectorArgs: PostgresVectorStoreArgs = {
  metadataColumns: ["page", "source"],
};

// PostgresVectorStore instantiation
const vectorStore = await PostgresVectorStore.initialize(
  engine,
  embeddingService,
  "my_vector_store_table",
  pvectorArgs
);

벡터 스토어 관리 (Manage vector store)

벡터 스토어에 문서 추가 (Add documents to vector store)

벡터 스토어에 문서를 추가하려면 id를 전달하거나 전달하지 않고 할 수 있어요.

import type { Document } from "@langchain/core/documents";

const document1: Document = {
  pageContent: "The powerhouse of the cell is the mitochondria",
  metadata: { page: 0, source: "https://example.com" },
};

const document2: Document = {
  pageContent: "Buildings are made out of brick",
  metadata: { page: 1, source: "https://example.com" },
};

const document3: Document = {
  pageContent: "Mitochondria are made out of lipids",
  metadata: { page: 2, source: "https://example.com" },
};

const document4: Document = {
  pageContent: "The 2024 Olympics are in Paris",
  metadata: { page: 3, source: "https://example.com" },
};

const documents = [document1, document2, document3, document4];

const ids = [crypto.randomUUID(), crypto.randomUUID(), crypto.randomUUID(), crypto.randomUUID()];

await vectorStore.addDocuments(documents, { ids: ids });

벡터 스토어에서 문서 삭제 (Delete documents from vector store)

삭제할 id 배열을 전달해 벡터 스토어에서 하나 이상의 문서를 삭제할 수 있어요:

// deleting a document
const id1 = ids[0];
await vectorStore.delete({ ids: [id1] });

// deleting more than one document
await vectorStore.delete({ ids: ids });

문서 검색 (Search for documents)

벡터 스토어가 생성되고 관련 문서가 추가되면 체인이나 에이전트 실행 중에 이를 쿼리하고 싶을 거예요.

직접 쿼리 (Query directly)

간단한 유사도 검색은 다음과 같이 수행할 수 있어요:

const filter = `"source" = "https://example.com"`;

const results = await vectorStore.similaritySearch("biology", 2, filter);

for (const doc of results) {
  console.log(`* ${doc.pageContent} [${JSON.stringify(doc.metadata, null)}]`);
}

유사도 검색을 실행하고 대응하는 점수를 받으려면 다음을 실행할 수 있어요:

const filter = `"source" = "https://example.com"`;
const resultsWithScores = await vectorStore.similaritySearchWithScore(
  "biology",
  2,
  filter
);

for (const [doc, score] of resultsWithScores) {
  console.log(
    `* [SIM=${score.toFixed(3)}] ${doc.pageContent} [${JSON.stringify(doc.metadata)}]`
  );
}

최대 한계 관련성(Maximal marginal relevance)은 쿼리에 대한 유사성과 선택된 문서 간의 다양성을 최적화해요.

const options = {
  k: 4,
  filter: `"source" = 'https://example.com'`,
};

const results = await vectorStore.maxMarginalRelevanceSearch("biology", options);

for (const doc of results) {
  console.log(`* ${doc.pageContent} [${JSON.stringify(doc.metadata, null)}]`);
}

출처: 문서

본문

PostgresVectorStore는 Google Cloud SQL for PostgreSQL에 벡터를 저장·검색하는 통합이에요. @langchain/google-cloud-sql-pg 패키지에서 PostgresEngine.fromInstance로 연결을 만들고 initVectorstoreTable로 테이블을 초기화한 뒤 PostgresVectorStore.initialize로 벡터 스토어를 생성해요. 문서 추가·삭제, similaritySearch·similaritySearchWithScore·maxMarginalRelevanceSearch 같은 검색을 지원해요.

더 알아보기 (Learn more)