IBM watsonx.ai 통합

LangChain JavaScript로 IBM watsonx.ai 임베딩 모델과 통합하는 방법을 안내할게요.

출처: 문서

본문

이 문서는 LangChain으로 IBM watsonx.ai 임베딩 모델을 시작하는 데 도움을 줘요. IBM watsonx.ai 기능과 구성 옵션에 대한 자세한 문서는 API 레퍼런스를 참고하세요.

개요

통합 세부 정보

클래스	패키지	Local	Py 지원	Downloads	Version
`WatsonxEmbeddings`	`@langchain/ibm`	❌	✅

설정

IBM WatsonxAI 임베딩에 접근하려면 IBM watsonx.ai 계정을 만들고 API 키 또는 다른 종류의 자격 증명을 받은 뒤 @langchain/ibm 통합 패키지를 설치해야 해요.

자격 증명

IBM Cloud에서 IBM watsonx.ai에 가입하고 API 키를 생성하거나 아래 제시된 다른 인증 방식을 제공하세요.

IAM 인증

export WATSONX_AI_AUTH_TYPE=iam
export WATSONX_AI_APIKEY=<YOUR-APIKEY>

Bearer 토큰 인증

export WATSONX_AI_AUTH_TYPE=bearertoken
export WATSONX_AI_BEARER_TOKEN=<YOUR-BEARER-TOKEN>

IBM watsonx.ai 소프트웨어 인증

export WATSONX_AI_AUTH_TYPE=cp4d
export WATSONX_AI_USERNAME=<YOUR_USERNAME>
export WATSONX_AI_PASSWORD=<YOUR_PASSWORD>
export WATSONX_AI_URL=<URL>

이 값들이 환경 변수에 들어가고 객체가 초기화되면 인증이 자동으로 진행돼요.

이 값들을 새 인스턴스의 매개변수로 전달해 인증할 수도 있어요.

IAM 인증

import { WatsonxEmbeddings } from "@langchain/ibm";

const props = {
  version: "YYYY-MM-DD",
  serviceUrl: "<SERVICE_URL>",
  projectId: "<PROJECT_ID>",
  watsonxAIAuthType: "iam",
  watsonxAIApikey: ***
};
const instance = new WatsonxEmbeddings(props);

Bearer 토큰 인증

import { WatsonxEmbeddings } from "@langchain/ibm";

const props = {
  version: "YYYY-MM-DD",
  serviceUrl: "<SERVICE_URL>",
  projectId: "<PROJECT_ID>",
  watsonxAIAuthType: "bearertoken",
  watsonxAIBearerToken: "<YOUR-BEARERTOKEN>",
};
const instance = new WatsonxEmbeddings(props);

IBM watsonx.ai 소프트웨어 인증

import { WatsonxEmbeddings } from "@langchain/ibm";

const props = {
  version: "YYYY-MM-DD",
  serviceUrl: "<SERVICE_URL>",
  projectId: "<PROJECT_ID>",
  watsonxAIAuthType: "cp4d",
  watsonxAIUsername: "<YOUR-USERNAME>",
  watsonxAIPassword: "<YOUR-PASSWORD>",
  watsonxAIUrl: "<url>",
};
const instance = new WatsonxEmbeddings(props);

모델 호출의 자동 추적(tracing)을 원한다면 아래 주석을 해제해 LangSmith API 키를 설정할 수도 있어요:

# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

설치

LangChain IBM watsonx.ai 통합은 @langchain/ibm 패키지에 있어요:

```bash npm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npm install @langchain/ibm @langchain/core ```

yarn add @langchain/ibm @langchain/core

pnpm add @langchain/ibm @langchain/core

인스턴스 생성

이제 모델 객체를 생성하고 텍스트를 임베딩할 수 있어요:

import { WatsonxEmbeddings } from "@langchain/ibm";

const embeddings = new WatsonxEmbeddings({
  version: "YYYY-MM-DD",
  serviceUrl: process.env.API_URL,
  projectId: "<PROJECT_ID>",
  spaceId: "<SPACE_ID>",
  model: "<MODEL_ID>",
});

참고:

진행하려면 spaceId 또는 projectId를 제공해야 해요.
프로비저닝된 서비스 인스턴스의 리전에 따라 올바른 serviceUrl을 사용하세요.

Model Gateway

import { WatsonxEmbeddings } from "@langchain/ibm";

const instance = new WatsonxEmbeddings({
  version: "YYYY-MM-DD",
  serviceUrl: process.env.API_URL,
  model: "<ALIAS_MODEL_ID>",
  modelGateway: true,
});

인덱싱 및 검색

임베딩 모델은 데이터 인덱싱과 나중 검색 모두의 일부로, 검색 증강 생성(RAG) 흐름에서 자주 사용돼요. 더 자세한 지침은 Learn 탭의 RAG 튜토리얼을 참고하세요.

아래에서 위에서 초기화한 embeddings 객체로 데이터를 인덱싱하고 검색하는 방법을 확인하세요. 이 예제에서는 데모 MemoryVectorStore를 사용해 샘플 문서를 인덱싱하고 검색할 거예요.

// Create a vector store with a sample text
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";

const text = "LangChain is the framework for building context-aware reasoning applications";

const vectorstore = await MemoryVectorStore.fromDocuments(
  [{ pageContent: text, metadata: {} }],
  embeddings,
);

// Use the vector store as a retriever that returns a single document
const retriever = vectorstore.asRetriever(1);

// Retrieve the most similar text
const retrievedDocuments = await retriever.invoke("What is LangChain?");

retrievedDocuments[0].pageContent;

LangChain is the framework for building context-aware reasoning applications

직접 사용

내부적으로 vectorstore와 retriever 구현은 fromDocuments에 사용된 텍스트와 retriever의 invoke 연산에 대해 각각 embeddings.embedDocument(...) 와 embeddings.embedQuery(...)를 호출해 임베딩을 만들 어요.

이 메서드들을 직접 호출해 자신의 사용 사례에 대한 임베딩을 얻을 수 있어요.

단일 텍스트 임베딩

embedQuery로 검색을 위한 쿼리를 임베딩할 수 있어요. 이는 쿼리에 특화된 벡터 표현을 생성해요:

    const singleVector = await embeddings.embedQuery(text);
    singleVector.slice(0, 10);

[
   -0.017436018,  -0.01469498,
   -0.015685871, -0.013543149,
  -0.0011519607, -0.008123747,
    0.015286108, -0.023845721,
    -0.02454774,   0.07235078
]

여러 텍스트 임베딩

embedDocuments로 인덱싱을 위한 여러 텍스트를 임베딩할 수 있어요. 이 메서드에 사용되는 내부는 쿼리 임베딩과 다를 수 있지만(다를 필요는 없음) 있어요:

    const text2 = "LangGraph is a library for building stateful, multi-actor applications with LLMs";

    const vectors = await embeddings.embedDocuments([text, text2]);

    console.log(vectors[0].slice(0, 10));
    console.log(vectors[1].slice(0, 10));

[
  -0.017436024, -0.014695002,
   -0.01568589, -0.013543164,
  -0.001151976, -0.008123703,
   0.015286064, -0.023845702,
  -0.024547677,   0.07235076
]
[
     0.03278884, -0.017893745,
  -0.0027520044,  0.016506646,
    0.028271576,  -0.01284331,
    0.014344065, -0.007968607,
    -0.03899479,  0.039327156
]

API 레퍼런스

모든 기능과 구성에 대한 자세한 문서는 API 레퍼런스를 참고하세요: api_ref_module

[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/embeddings/ibm.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).

더 알아보기

이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.