본문 바로가기
WIKI 기술 지식 베이스

Configuring agents for semantic search

원문 보기 위키 갱신

출처: 문서

본문

시맨틱 검색을 위한 에이전트 구성

임베딩이 포함된 벡터 인덱스를 갖고 있고 사용자 의도에 따라 agentic search가 자동으로 시맨틱 검색을 수행하기를 원한다면, 에이전트에 임베딩 모델 정보를 구성해야 합니다. 이를 통해 에이전트는 정확한 텍스트 일치가 아닌 시맨틱 유사성을 검색하는 neural 쿼리를 생성할 수 있으며, 개념적인 질문에 대해 더 관련성 높은 결과를 제공합니다.

시맨틱 검색을 위해 에이전트를 구성하면, 에이전트는 쿼리 시점에 전통적인 키워드 검색과 시맨틱 벡터 검색 중에서 선택합니다.

임베딩 모델 ID가 제공되더라도, 에이전트는 쿼리 의도와 컨텍스트를 기반으로 neural(시맨틱) 검색을 사용할지 lexical 검색을 사용할지 스스로 결정합니다. 예를 들어 날짜 필터나 정확히 일치하는 쿼리는 lexical 검색을 사용하고, 개념적인 쿼리는 neural 검색을 사용합니다. {: .note}

사전 요구 사항
시맨틱 검색을 사용하기 전에 텍스트 임베딩 모델을 설정해야 합니다. 자세한 정보는 모델 선택을 참조하세요. {: .note}

1단계: 벡터 인덱스 구성

먼저 벡터 인덱스를 구성합니다.

1(a)단계: 임베딩 모델 생성

시맨틱 검색을 위해 텍스트를 벡터 표현으로 변환할 임베딩 모델을 등록합니다:

POST /_plugins/_ml/models/_register
{
  "name": "Bedrock embedding model",
  "function_name": "remote",
  "description": "Bedrock text embedding model v2",
  "connector": {
    "name": "Amazon Bedrock Connector: embedding",
    "description": "The connector to bedrock Titan embedding model",
    "version": 1,
    "protocol": "aws_sigv4",
    "parameters": {
      "region": "your-aws-region",
      "service_name": "bedrock",
      "model": "amazon.titan-embed-text-v2:0",
      "dimensions": 1024,
      "normalize": true,
      "embeddingTypes": [
        "float"
      ]
    },
    "credential": {
      "access_key": "your-access-key",
      "secret_key": "your-secret-key",
      "session_token": "your-session-token"
    },
    "actions": [
      {
        "action_type": "predict",
        "method": "POST",
        "url": "https://bedrock-runtime.${parameters.region}.amazonaws.com/model/${parameters.model}/invoke",
        "headers": {
          "content-type": "application/json",
          "x-amz-content-sha256": "required"
        },
        "request_body": "{ \"inputText\": \"${parameters.inputText}\", \"dimensions\": ${parameters.dimensions}, \"normalize\": ${parameters.normalize}, \"embeddingTypes\": ${parameters.embeddingTypes} }",
        "pre_process_function": "connector.pre_process.bedrock.embedding",
        "post_process_function": "connector.post_process.bedrock.embedding"
      }
    ]
  }
}

{% include copy-curl.html %}

1(b)단계: ingest pipeline 생성

문서 수집 시 텍스트 필드에 대한 임베딩을 자동으로 생성하는 ingest pipeline을 생성합니다:

PUT /_ingest/pipeline/my_bedrock_embedding_pipeline
{
  "description": "text embedding pipeline",
  "processors": [
    {
      "text_embedding": {
        "model_id": "fxzel5kB-5P992SCH-qM",
        "field_map": {
          "content_text": "content_embedding"
        }
      }
    }
  ]
}

{% include copy-curl.html %}

1(c)단계: ingest pipeline을 사용한 벡터 인덱스 생성

텍스트 콘텐츠와 벡터 임베딩 양쪽에 대한 매핑을 갖춘 벡터 인덱스를 생성하고, ingest pipeline을 사용해 문서를 자동으로 처리합니다:

PUT /research_papers
{
  "settings": {
    "index": {
      "default_pipeline": "my_bedrock_embedding_pipeline",
      "knn": "true"
    }
  },
  "mappings": {
    "properties": {
      "content_embedding": {
        "type": "knn_vector",
        "dimension": 1024,
        "method": {
          "name": "hnsw",
          "engine": "lucene"
        }
      },
      "published_date": {
        "type": "date"
      },
      "rating": {
        "type": "integer"
      }
    }
  }
}

{% include copy-curl.html %}

1(d)단계: 벡터 인덱스에 데이터 수집

인덱스에 연구 논문 문서를 추가합니다. ingest pipeline이 content_text 필드에 대한 임베딩을 자동으로 생성합니다:

POST /_bulk
{ "index": { "_index": "research_papers", "_id": "1" } }
{ "content_text": "Autonomous robotic systems for warehouse automation and industrial manufacturing", "published_date": "2024-05-15", "rating": 5 }
{ "index": { "_index": "research_papers", "_id": "2" } }
{ "content_text": "Gene expression analysis and CRISPR-Cas9 genome editing applications in cancer research", "published_date": "2024-06-02", "rating": 4 }
{ "index": { "_index": "research_papers", "_id": "3" } }
{ "content_text": "Reinforcement learning algorithms for sequential decision making and optimization problems", "published_date": "2024-03-20", "rating": 5 }
{ "index": { "_index": "research_papers", "_id": "4" } }
{ "content_text": "Climate change impact on coral reef ecosystems and marine biodiversity conservation", "published_date": "2024-04-10", "rating": 4 }
{ "index": { "_index": "research_papers", "_id": "5" } }
{ "content_text": "Tectonic plate movements and earthquake prediction using geological fault analysis", "published_date": "2024-01-22", "rating": 4 }

{% include copy-curl.html %}

2단계: agentic search 구성

다음으로 agentic search를 구성합니다.

2(a)단계: agentic search용 모델 생성

대화형 에이전트와 QueryPlanningTool 양쪽에서 사용할 모델을 등록합니다:

POST /_plugins/_ml/models/_register
{
  "name": "My OpenAI model: gpt-5",
  "function_name": "remote",
  "description": "Model for agentic search with neural queries",
  "connector": {
    "name": "My openai connector: gpt-5",
    "description": "The connector to openai chat model",
    "version": 1,
    "protocol": "http",
    "parameters": {
      "model": "gpt-5"
    },
    "credential": {
      "openAI_key": "<OPEN AI KEY>"
    },
    "actions": [
      {
        "action_type": "predict",
        "method": "POST",
        "url": "https://api.openai.com/v1/chat/completions",
        "headers": {
          "Authorization": "Bearer ${credential.openAI_key}"
        },
        "request_body": "{ \"model\": \"${parameters.model}\", \"messages\": [{\"role\":\"developer\",\"content\":\"${parameters.system_prompt}\"},${parameters._chat_history:-}{\"role\":\"user\",\"content\":\"${parameters.user_prompt}\"}${parameters._interactions:-}], \"reasoning_effort\":\"low\"${parameters.tool_configs:-}}"
      }
    ]
  }
}

{% include copy-curl.html %}

2(b)단계: 에이전트 생성

agentic search를 위한 에이전트를 생성합니다. 에이전트가 neural 쿼리를 사용해 시맨틱 검색을 수행할 수 있게 하려면 다음 방법 중 하나로 임베딩 모델을 구성해야 합니다:

  • 옵션 1: search pipeline에 임베딩 모델을 구성합니다(더 쉽게 업데이트할 수 있어 권장됨).
  • 옵션 2: 에이전트 구성에 임베딩 모델을 구성합니다.

옵션 1: 임베딩 모델 ID 없이 에이전트 생성(권장)

search pipeline에서 embedding_model_id를 지정할 계획이라면 이 옵션을 사용합니다:

POST /_plugins/_ml/agents/_register
{
  "name": "GPT 5 Agent for Agentic Search",
  "type": "conversational",
  "description": "Use this for Agentic Search",
  "llm": {
    "model_id": "your-agent-model-id",
    "parameters": {
      "max_iteration": 15
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "openai/v1/chat/completions"
  },
  "tools": [
    {
      "type": "QueryPlanningTool",
      "parameters": {
        "model_id": "your-qpt-model-id"
      }
    }
  ],
  "app_type": "os_chat"
}

{% include copy-curl.html %}

옵션 2: 임베딩 모델 ID를 포함해 에이전트 생성

또는 에이전트의 llm.parameters에 embedding_model_id를 포함합니다:

POST /_plugins/_ml/agents/_register
{
  "name": "GPT 5 Agent for Agentic Search",
  "type": "conversational",
  "description": "Use this for Agentic Search",
  "llm": {
    "model_id": "your-agent-model-id",
    "parameters": {
      "max_iteration": 15,
      "embedding_model_id": "your-embedding-model-id-from-step1"
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "parameters": {
    "_llm_interface": "openai/v1/chat/completions"
  },
  "tools": [
    {
      "type": "QueryPlanningTool",
      "parameters": {
        "model_id": "your-qpt-model-id"
      }
    }
  ],
  "app_type": "os_chat"
}

{% include copy-curl.html %}

2(c)단계: search pipeline 생성

agentic_query_translator 프로세서가 포함된 search pipeline을 생성합니다. 자세한 정보는 Agentic query translator 프로세서를 참조하세요.

2(b)단계에서 옵션 1을 사용한 경우(권장): search pipeline에 embedding_model_id를 포함합니다:

PUT _search/pipeline/my_pipeline
{
  "request_processors": [
    {
      "agentic_query_translator": {
        "agent_id": "your-agent-id-from-step-2b",
        "embedding_model_id": "your-embedding-model-id-from-step1"
      }
    }
  ]
}

{% include copy-curl.html %}

2(b)단계에서 옵션 2를 사용한 경우: embedding_model_id 없이 search pipeline을 생성합니다:

PUT _search/pipeline/my_pipeline
{
  "request_processors": [
    {
      "agentic_query_translator": {
        "agent_id": "your-agent-id-from-step-2b"
      }
    }
  ]
}

{% include copy-curl.html %}

에이전트와 search pipeline 양쪽에서 embedding_model_id를 지정하면 search pipeline 구성이 우선합니다. {: .note}

3단계: agentic search 실행

다양한 구성으로 agentic search를 실행합니다.

시맨틱 검색 실행

시맨틱 이해가 필요한 질문으로 agentic search를 수행합니다:

POST /research_papers/_search?search_pipeline=my_pipeline
{
  "query": {
    "agentic": {
      "query_text": "Show me 3 robots training related research papers "
    }
  }
}

{% include copy-curl.html %}

에이전트가 시맨틱 검색이 필요하다는 사실을 성공적으로 식별합니다. ext 객체는 QueryPlanningTool이 임베딩 모델 ID를 사용해 neural 쿼리를 성공적으로 생성했음을 보여줍니다. 응답에는 시맨틱 유사도에 따라 순위가 매겨진 일치하는 연구 논문들이 포함됩니다:

{
  "took": 10509,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 5,
      "relation": "eq"
    },
    "max_score": 0.40031588,
    "hits": [
      {
        "_index": "research_papers",
        "_id": "1",
        "_score": 0.40031588,
        "_source": {
          "content_text": "Autonomous robotic systems for warehouse automation and industrial manufacturing",
          "rating": 5,
          "content_embedding": ["<redacted>"],
          "published_date": "2024-05-15"
        }
      },
      {
        "_index": "research_papers",
        "_id": "3",
        "_score": 0.36390686,
        "_source": {
          "content_text": "Reinforcement learning algorithms for sequential decision making and optimization problems",
          "rating": 5,
          "content_embedding": ["<redacted>"],
          "published_date": "2024-03-20"
        }
      },
      {
        "_index": "research_papers",
        "_id": "5",
        "_score": 0.34401828,
        "_source": {
          "content_text": "Tectonic plate movements and earthquake prediction using geological fault analysis",
          "rating": 4,
          "content_embedding": ["<redacted>"],
          "published_date": "2024-01-22"
        }
      }
    ]
  },
  "ext": {
    "agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool]\nFirst I used: ListIndexTool — input: \"[]\"; context gained: \"Found indices; 'research_papers' appears relevant\"\nSecond I used: IndexMappingTool — input: \"[\"research_papers\"]\"; context gained: \"Index has text content and an embedding field suitable for neural search\"\nThird I used: query_planner_tool — qpt.question: \"Show me 3 research papers related to robots training.\"; index_name_provided: \"research_papers\"\nValidation: qpt output is valid and limits results to 3 using neural search with the provided model.",
    "memory_id": "jhzpl5kB-5P992SCwOqe",
    "dsl_query": "{\"size\":3.0,\"query\":{\"neural\":{\"content_embedding\":{\"model_id\":\"fxzel5kB-5P992SCH-qM\",\"k\":100.0,\"query_text\":\"robots training\"}}}}"
  }
}

필터를 사용한 전통적인 검색 실행

다음으로, 시맨틱 이해가 아닌 필터링이 필요한 질문으로 agentic search를 수행합니다:

POST /research_papers/_search?search_pipeline=my_pipeline
{
  "query": {
    "agentic": {
      "query_text": "Show me papers published after 2024 May"
    }
  }
}

{% include copy-curl.html %}

에이전트는 이 쿼리를 날짜 기반 필터 쿼리로 인식하고, neural 쿼리 대신 전통적인 range 쿼리를 생성합니다:

{
  "took": 8522,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "research_papers",
        "_id": "2",
        "_score": null,
        "_source": {
          "content_text": "Gene expression analysis and CRISPR-Cas9 genome editing applications in cancer research",
          "rating": 4,
          "content_embedding": ["<redacted>"],
          "published_date": "2024-06-02"
        },
        "sort": [
          1717286400000
        ]
      }
    ]
  },
  "ext": {
    "agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool]\nFirst I used: query_planner_tool — qpt.question: \"Show me papers published after May 2024.\"; index_name_provided: \"research_papers\"\nValidation: qpt output is valid JSON and matches the user request with the specified date filter and sorting.",
    "memory_id": "vBzyl5kB-5P992SCI-o1",
    "dsl_query": "{\"size\":10.0,\"query\":{\"bool\":{\"filter\":[{\"range\":{\"published_date\":{\"gt\":\"2024-05-31T23:59:59Z\"}}}]}},\"sort\":[{\"published_date\":{\"order\":\"desc\"}}]}"
  }
}

쿼리 텍스트에 임베딩 모델 지정

임베딩 모델 ID를 재정의하려면 쿼리를 보낼 때 자연어 query_text에 임베딩 모델 ID를 직접 포함할 수 있습니다. 이는 search pipeline이나 에이전트에 구성된 embedding_model_id보다 우선합니다:

POST /research_papers/_search?search_pipeline=my_pipeline
{
  "query": {
    "agentic": {
      "query_text": "Show me 3 robots training related research papers use this model id for neural search:fxzel5kB-5P992SCH-qM "
    }
  }
}

{% include copy-curl.html %}

에이전트가 쿼리 텍스트에서 직접 임베딩 모델 ID를 성공적으로 추출하고 적절한 neural DSL 쿼리를 생성합니다:

{
  "took": 14989,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "max_score": 0.38957736,
    "hits": [
      {
        "_index": "research_papers",
        "_id": "1",
        "_score": 0.38957736,
        "_source": {
          "content_text": "Autonomous robotic systems for warehouse automation and industrial manufacturing",
          "rating": 5,
          "content_embedding": [],
          "published_date": "2024-05-15"
        }
      },
      {
        "_index": "research_papers",
        "_id": "3",
        "_score": 0.36386627,
        "_source": {
          "content_text": "Reinforcement learning algorithms for sequential decision making and optimization problems",
          "rating": 5,
          "content_embedding": [],
          "published_date": "2024-03-20"
        }
      },
      {
        "_index": "research_papers",
        "_id": "2",
        "_score": 0.35789147,
        "_source": {
          "content_text": "Gene expression analysis and CRISPR-Cas9 genome editing applications in cancer research",
          "rating": 4,
          "content_embedding": [],
          "published_date": "2024-06-02"
        }
      }
    ]
  },
  "ext": {
    "agent_steps_summary": "I have these tools available: [ListIndexTool, IndexMappingTool, query_planner_tool]\nFirst I used: ListIndexTool — input: \"\"; context gained: \"Found indices, including research_papers with 5 documents\"\nSecond I used: IndexMappingTool — input: \"research_papers\"; context gained: \"Index exists and contains text and embedding fields suitable for neural search\"\nThird I used: query_planner_tool — qpt.question: \"Show me 3 research papers related to robot training.\"; index_name_provided: \"research_papers\"\nValidation: qpt output is valid neural search DSL using the provided model ID and limits results to 3.",
    "memory_id": "whz1l5kB-5P992SCPOqn",
    "dsl_query": "{\"size\":3.0,\"query\":{\"neural\":{\"content_embedding\":{\"model_id\":\"fxzel5kB-5P992SCH-qM\",\"k\":100.0,\"query_text\":\"research papers related to robot training\"}}},\"sort\":[{\"_score\":{\"order\":\"desc\"}}],\"track_total_hits\":false}"
  }
}

관련 문서

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.