Db2 Vector Search Tool

Db2 Vector Search Tool

IBM Db2 네이티브 VECTOR_DISTANCE 기능을 사용해 CrewAI 에이전트에 시맨틱 벡터 검색을 제공하는 도구예요.

출처: 문서

본문

DB2VectorSearchTool

설명 (Description)

네이티브 VECTOR_DISTANCE 함수를 사용해 IBM Db2 테이블에 대해 시맨틱 벡터 유사도 검색을 수행합니다. 설정 가능한 거리 메트릭, OpenAI 또는 커스텀 임베딩, 메타데이터 필터링, 결과 셰이핑을 지원합니다.

설치 (Installation)

pip install ibm_db openai

또는 uv로:

uv add ibm_db openai

환경 변수 (Environment Variables)

OPENAI_API_KEY=your_openai_key          # Required when using default OpenAI embeddings
DB2_CONNECTION_STRING=DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;

기본 사용법 (Basic Usage)

from crewai import Agent
from crewai_tools import DB2VectorSearchTool

tool = DB2VectorSearchTool(
    connection_string="DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;",
    table_name="documents",
    vector_column="embedding",
)

agent = Agent(
    role="Research Assistant",
    goal="Find relevant information in documents",
    tools=[tool],
)

전체 시맨틱 검색 워크플로 (Full Semantic Search Workflow)

import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process
from crewai_tools import DB2VectorSearchTool

load_dotenv()

db2_tool = DB2VectorSearchTool(
    connection_string=os.getenv("DB2_CONNECTION_STRING"),
    table_name="documents",
    vector_column="embedding",
    return_columns=["content", "category"],
    limit=3,
    distance_metric="COSINE",
    max_distance=0.35,
)

search_agent = Agent(
    role="Senior Semantic Search Agent",
    goal="Find and analyse documents based on semantic search",
    backstory="You are an expert research assistant who can find relevant information using semantic search in a Db2 database.",
    tools=[db2_tool],
    verbose=True,
)

answer_agent = Agent(
    role="Senior Answer Assistant",
    goal="Generate answers based on retrieved context",
    backstory="You are an expert assistant who generates answers from provided context.",
    tools=[db2_tool],
    verbose=True,
)

search_task = Task(
    description="""Search for relevant documents about {query}.
    Include the relevant information found, vector distances, and returned fields.""",
    agent=search_agent,
)

answer_task = Task(
    description="Given the retrieved Db2 context, generate a final answer.",
    agent=answer_agent,
)

crew = Crew(
    agents=[search_agent, answer_agent],
    tasks=[search_task, answer_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff(inputs={"query": "What is the role of X in the document?"})
print(result)

도구 파라미터 (Tool Parameters)

파라미터 타입 기본값 설명
connection_string str 필수 Db2 연결 문자열. 형식: DATABASE=x;HOSTNAME=x;PORT=50000;PROTOCOL=TCPIP;UID=x;PWD=x;
table_name str "documents" 검색할 테이블. schema.table 표기 지원.
vector_column str "embedding" 벡터 임베딩을 저장하는 컬럼.
embedding_model str "text-embedding-3-large" 커스텀 임베딩 함수가 제공되지 않을 때 사용되는 OpenAI 모델.
return_columns list[str] ["content"] 각 결과에 포함할 컬럼. 최소 하나 이상 포함해야 합니다.
limit int 3 최대 결과 수 (1–100).
distance_metric str "COSINE" Db2 거리 메트릭. 아래 지원 값 참고.
max_distance float | None None 이 값을 초과하는 거리의 결과는 제외.
custom_embedding_fn Callable[[str], list[float]] | None None 커스텀 임베딩 함수. 제공되면 OpenAI를 대체.

지원 거리 메트릭 (Supported Distance Metrics)

다음 값은 Db2 VECTOR_DISTANCE 함수에 직접 매핑됩니다:

  • COSINE
  • EUCLIDEAN
  • EUCLIDEAN_SQUARED
  • DOT
  • HAMMING
  • MANHATTAN

참고: IBM Db2 VECTOR_DISTANCE 문서

스키마 파라미터 (쿼리별) (Schema Parameters per query)

파라미터 타입 필수 설명
query str ✅ 검색 쿼리.
filter_by str | None ❌ 메타데이터 필터링용 컬럼 이름. filter_value와 함께 사용해야 합니다.
filter_value Any | None ❌ 필터링할 값. filter_by와 함께 사용해야 합니다.

반환 형식 (Return Format)

{
  "success": true,
  "results": [
    {
      "distance": 0.1401,
      "data": {
        "content": "Document content here",
        "category": "research"
      }
    }
  ]
}

에러 시:

{
  "success": false,
  "error": "Description of what went wrong",
  "error_type": "ExceptionClassName"
}

메타데이터 필터링 (Metadata Filtering)

result = db2_tool.run(
    query="machine learning",
    filter_by="category",
    filter_value="research",
)

filter_by와 filter_value는 항상 함께 제공해야 합니다. 하나만 제공하면 검증 에러가 발생합니다.

커스텀 임베딩 (Custom Embeddings)

custom_embedding_fn을 제공해 어떤 임베딩 모델이든 사용할 수 있어요:

from sentence_transformers import SentenceTransformer
from crewai_tools import DB2VectorSearchTool

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

def custom_embeddings(text: str) -> list[float]:
    return model.encode(text).tolist()

tool = DB2VectorSearchTool(
    connection_string="DATABASE=TESTDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;",
    table_name="documents",
    custom_embedding_fn=custom_embeddings,
)

custom_embedding_fn이 제공되면 OPENAI_API_KEY는 필요하지 않습니다.

보안 기능 (Security Features)

  • SQL 식별자 검증 (테이블·컬럼 이름은 ^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)?$와 일치해야 함)
  • 파라미터화된 SQL 쿼리 — 값은 절대 SQL 문자열에 직접 삽입되지 않음
  • 거리 메트릭 화이트리스트 — 유효한 Db2 메트릭 이름만 허용

더 알아보기 (Learn more)