728x90
반응형

Neocarta를 사용하여 GCP에서 그래프 기반 의미 계층 구축

Neocarta를 사용하여 Neo4j에서 에이전트 애플리케이션을 위한 의미 계층 그래프를 쉽게 구축

소개

의미 체계 계층은 점점 더 에이전트 시스템의 귀중한 자산이 되고 있습니다. 이는 AI가 기본 데이터를 더 잘 이해하고 대규모 엔터프라이즈 데이터 환경을 처리할 수 있도록 돕습니다. 현대 의미 계층의 주요 속성은 서로 다른 많은 데이터 자산 간의 관계입니다. 열 이름은 어떤 용어로 해석됩니까? 이 의미를 공유하는 다른 열이 있으며, 이를 사용하여 새로운 통찰력을 얻을 수 있는 방법은 무엇입니까? 그래프 지원 의미 계층에 액세스할 수 있는 에이전트는 점을 연결하고 데이터의 바다에서 답을 찾을 수 있는 위치를 이해하는 데 아무런 문제가 없습니다.

이번 글에서는 사용법을 알아보겠습니다.네오카르타 Python 라이브러리GCP BigQuery 및 Knowledge Catalog(이전 Dataplex Universal Catalog)의 정보로부터 Neo4j의 시맨틱 레이어 그래프를 쉽게 생성합니다. 그런 다음 Neocarta MCP 서버를 사용하여 에이전트가 의미 계층을 통해 즉각적인 통찰력을 얻을 수 있도록 합니다.

GitHub – neo4j-labs/neocarta: 쿼리 라우팅, 쿼리 생성 및 데이터 검색을 위한 의미 계층 그래프 생성을 위해 구축된 라이브러리

Neocarta는 Neo4j Labs 프로젝트이며 빠르게 개발되고 있습니다.

우리는 다음과 같은 의미 계층 아키텍처를 템플릿으로 사용합니다. 피드백 및 메모리 구성 요소와 같은 일부 측면은 이 연습에서 구현되지 않습니다.

의미 계층 아키텍처

의미 계층은 먼저 0단계에서 소스 데이터로 채워집니다. 여기에는 데이터베이스, 데이터 카탈로그, 쿼리 로그, 지원 문서 및 온톨로지와 같은 다양한 데이터 소스가 포함됩니다. 이 데이터는 기본 데이터 시스템의 구조를 제공하고 이를 활용하는 방법에 대한 이해를 용이하게 합니다.

데이터가 로드되면 사용자는 에이전트 채팅 인터페이스와 같은 소비 계층의 리소스와 상호 작용할 수 있습니다. 그러면 컨텍스트 MCP 서버를 통해 Neo4j 의미 계층에서 컨텍스트를 먼저 검색하는 에이전트 워크플로가 시작됩니다. 그런 다음 에이전트 계층의 에이전트는 이 컨텍스트를 사용하여 적절한 쿼리 MCP 서버를 선택하고 소스 데이터베이스에 대해 쿼리를 실행합니다. 그런 다음 에이전트 레이어는 결과를 요약하고 사용자에게 응답을 반환합니다.

요구사항

이 데모를 처음부터 끝까지 실행하려면 몇 가지 리소스 설정이 필요합니다.

  • 다음 항목에 액세스할 수 있는 GCP 프로젝트BigQuery and 지식 카탈로그(Dataplex 유니버설 카탈로그)
  • gcloud CLI 도구
  • Neo4j 인스턴스 — 둘 중 하나현지의 or Aura
  • uv 패키지 관리자설치됨

그래프 데이터 모델

코드에 들어가기 전에 의미 계층의 모양을 이해해야 합니다. 우리가 구현할 두 가지 기본 구성 요소가 있습니다(더 많은 데이터 소스를 포함할 수 있지만 이에 대한 자세한 내용은 향후 문서에서 설명합니다).

의미론적 계층의 기초는 데이터베이스의 메타데이터입니다. 여기서는 그래프의 데이터베이스, 스키마, 테이블 및 열 계층 구조를 명시적으로 매핑합니다. 또한 외래 키 정의를 통해 또는 로그의 쿼리 패턴을 분석하여 서로 관련된 열을 캡처합니다.

메모:데이터베이스는 GCP 프로젝트에 매핑됩니다.스키마는 BigQuery 데이터세트에 매핑됩니다.

RDBMS 메타데이터 그래프 데이터 모델

두 번째 구성요소는 비즈니스 용어를 제공하는 용어집 정보입니다. 이러한 엔터티는 컨텍스트 검색과 관련하여 고급 검색 패턴을 허용합니다.

용어집 그래프 데이터 모델

용어집 하위 그래프는 다음과 같이 메타데이터 하위 그래프 위에 계층화됩니다. BusinessTerm 노드는 TAGGED_WITH 관계를 통해 테이블 ​​및 열 노드에 연결됩니다. 이를 통해 비즈니스 용어와의 연결을 통해 데이터 자산을 식별할 수 있습니다.

결합된 RDBMS 메타데이터 및 용어집 그래프 데이터 모델

데이터 소스

의미 체계 계층에는 BigQuery와 지식 카탈로그라는 두 가지 기본 데이터 소스가 있습니다. 이는 각각 스키마 메타데이터와 용어집 그래프 구성 요소를 제공합니다.

또한 쿼리 로그에서 메타데이터를 가져오는 방법도 보여드리겠습니다. 이는 외래 키에 의해 명시적으로 정의되지 않지만 대신 SQL 쿼리의 JOIN 조건에서 추론될 수 있는 관계로 스키마 메타데이터 그래프를 강화합니다.

다음은 각 소스에서 제공하는 그래프 항목입니다.

BigQuery

  • 열

지식 카탈로그(Dataplex)

  • 열
  • CTE

Neocarta에는 BigQuery, Dataplex, 쿼리 로그용 커넥터가 포함되어 있어 이 그래프를 쉽게 생성할 수 있습니다. 또한 다음과 같은 다른 소스도 지원합니다.OSIYAML 파일.

다른 많은 인기 있는 데이터 소스 커넥터도 곧 출시될 예정입니다.

그래프 만들기

이제 의미 체계의 그래프 데이터 모델과 데이터 소스를 이해했으므로 그래프 작성을 시작할 수 있습니다.

우리는 Neocarta GitHub 저장소의 데모 데이터세트 중 하나인 ACME Corp 데이터세트를 사용할 것입니다. 이 데이터에는 테이블 33개, 열 327개, 비즈니스 용어 76개가 포함되어 있습니다.

먼저,네오카르타 GitHub 저장소. 이 데모는 Neocarta v0.7.0에 고정될 예정이므로 저장소를 복제할 때 태그를 포함했는지 확인하세요.

git clone --branch neocarta-v0.7.0 https://github.com/neo4j-labs/neocarta.git

프로젝트 루트 디렉터리로 이동하여 .env.example 파일을 엽니다. 여기에 있는 내용을 기반으로 새 .env 파일을 만들어야 합니다.

참고: EMBEDDING_DIMENSIONS는 .env.example 파일에 없습니다. 선택적으로 이 변수를 추가하여 이를 지원하는 모델에 대해 기본값이 아닌 치수 값을 사용할 수 있습니다. 이는 Neocarta MCP 서버 구성에 적용됩니다. CLI 구성에 대한 자세한 내용은 다음을 참조하세요.

NEO4J_USERNAME=neo4j-username
NEO4J_PASSWORD=neo4j-password
NEO4J_URI=neo4j-uri
NEO4J_DATABASE=neo4j-database
GCP_PROJECT_ID=project-id
GCP_PROJECT_NUMBER=project-number
BIGQUERY_DATASET_ID=acme_corp
BIGQUERY_LOCATION=us
DATAPLEX_LOCATION=us
DATAPLEX_GLOSSARY_ID=acme-corp-glossary
# Text2SQL agent chat LLM - LiteLLM model id. Examples:
# gpt-4o-mini
# gemini-2.0-flash
# gpt-5.4-mini
AGENT_MODEL=gpt-5.4-mini
# Embeddings - LiteLLM model id.
# Examples:
# text-embedding-3-small (OpenAI)
# gemini-embedding-001 (Vertex AI)
EMBEDDING_MODEL=text-embedding-3-small
# EMBEDDING_DIMENSIONS=768
# Provider credentials - set the variables your chosen EMBEDDING_MODEL requires.
OPENAI_API_KEY=…
# GEMINI_API_KEY=…

참고: AGENT_MODEL 환경 변수는 내장된 CLI 에이전트를 사용하기로 결정한 경우에만 관련됩니다.에이전트 인터페이스에는 Claude Desktop과 같은 에이전트 애플리케이션을 사용하는 것이 좋습니다.

참고: Neocarta는 LiteLLM에서 지원하는 모든 임베딩 모델과 호환됩니다.

프로젝트 루트에 .env 파일을 생성한 후 다음을 실행하여 핵심 프로젝트 및 CLI 종속성을 설치합니다.

uv sync --extra cli

또한 GCP 인스턴스에 연결하려면 gcloud CLI에 로그인해야 합니다.

gcloud auth application-default login

이제 BigQuery 데이터베이스와 지식 카탈로그 용어집을 데모 데이터로 채울 수 있습니다. 사용할 데이터가 이미 있는 경우 이 단계를 건너뛸 수 있습니다.

먼저 BigQuery를 채웁니다.

uv run datasets/load_bigquery.py --dataset acme

이제 지식 카탈로그 용어집 데이터를 채울 수 있습니다.

참고: Neocarta의 지식 카탈로그에 대한 모든 참조는 Dataplex로 명명됩니다.

아래 명령은 용어집을 생성합니다.

datasets/dataplex/create_acme_glossary.sh

이 명령은 비즈니스 용어를 해당 데이터 자산에 연결합니다.

uv run datasets/dataplex/connect_acme_terms.py

이제 GCP 프로젝트가 데이터로 채워졌으므로 Neo4j에서 의미 계층을 생성할 수 있습니다. 이는 Neocarta CLI를 사용하여 수행됩니다. 우리는 Neocarta 프로젝트에 있기 때문에 CLI를 설치할 필요가 없습니다. 하지만 다른 상황에서는 PyPI에서 CLI를 설치할 수 있습니다.

pip install "neocarta[cli]"
# or 
uv add "neocarta[cli]"

Neo4j 인스턴스가 실행 중인지 확인한 후 다음 두 가지 CLI 명령을 실행하세요. 이 두 명령은 모두 데이터를 수집하고 기본 노드 세트(스키마의 테이블 및 열, 용어집의 BusinessTerm)에 대한 임베딩을 생성합니다.

참고: uv가 Neocarta 환경을 관리하기 때문에 여기서는 uv run을 사용하고 있습니다. 전역 설치는 uv run 접두사 없이 실행될 수 있습니다.

–embedding-dimensions 플래그를 사용하여 모델이 지원하는 경우 사용할 임베딩 차원을 정의할 수도 있습니다. 이는 두 CLI 명령 모두에 적용됩니다.

uv run neocarta bigquery schema --embeddings
uv run neocarta dataplex glossary --embeddings

이제 쿼리 로그도 구문 분석하여 의미 계층의 데이터 자산 간의 관계를 향상시킬 수 있습니다. 이렇게 하면 외래 키 정의에 캡처되지 않은 테이블과 열 사이에 추가 JOIN 논리를 추가할 수 있습니다. 새로운 데모 데이터 세트에는 쿼리 로그 데이터가 없으므로 이 섹션은 실행하지 않습니다. 기존 BigQuery 데이터세트에서 자유롭게 실행해 보세요.

참고: 쿼리 로그 커넥터는 의미 계층에 쿼리 및 CTE 노드도 저장합니다. 이는 소수의 예시로 참조될 수 있습니다.

쿼리 및 RDBMS 메타데이터 그래프 데이터 모델

아래 CLI 명령을 실행하여 BigQuery 쿼리 로그에 연결하고 Neo4j 의미 계층 그래프로 수집합니다. 시작 날짜 플래그를 원하는 날짜로 자유롭게 바꾸십시오. 참조CLI 문서구성에 대한 자세한 내용은

uv run neocarta bigquery logs --start-date 2026–01–01

다음은 결과 의미 계층 그래프의 스냅샷입니다. 왼쪽에는 Database(진한 보라색) → Schema(분홍색) → Table(황록색) → Column(주황색) 계층 구조가 있고, 오른쪽에는 Glossary(진한 보라색) → Category(갈색) → BusinessTerm(파란색)이 나열되어 있습니다.

Neo4j 의미 계층 그래프 스냅샷

의미 체계 계층에 에이전트 연결

이제 에이전트를 의미 계층 그래프에 연결할 차례입니다. 이 작업은 다음을 사용하여 쉽게 수행됩니다.네오카르타 MCP 서버. 이 MCP 서버는 Neocarta에 정의된 그래프 데이터 모델과 호환되도록 구축되었으며 그래프에서 사용 가능한 색인 및 엔터티에 따라 도구를 등록합니다.

그래프에 벡터 인덱스, 전체 텍스트 인덱스 및 BusinessTerm 노드가 있으므로 MCP 서버는 다음 도구 세트를 등록합니다.

  • 스키마별로 테이블 나열
  • 테이블 비즈니스 용어 하이브리드 검색으로 컨텍스트 파악
  • 열 비즈니스 용어 하이브리드 검색으로 컨텍스트 확인
  • 전체 메타데이터 스키마 가져오기(개발 및 디버깅에만 사용됨)

참고: 이름 및 설명 속성에 대한 전체 텍스트 색인이 자동으로 생성되지만 Python 라이브러리 커넥터 인수에서 해제할 수 있습니다.

두 가지 하이브리드 검색과 비즈니스 용어 도구는 가장 진보된 컨텍스트 검색 패턴을 갖추고 있습니다. 먼저 앵커 노드 풀을 식별하기 위해 세 가지 검색을 수행합니다.

  • 기본 항목 벡터 검색
  • BusinessTerm 전체 텍스트 검색
  • 기본 엔터티 전체 텍스트 검색

전체 텍스트 검색 부분은 먼저 BusinessTerm 노드를 식별한 다음 연결된 엔터티 노드(테이블 또는 열)를 탐색합니다. 그런 다음 이러한 엔터티 노드에서 전체 텍스트 검색이 다시 실행되고 정규화된 평균 점수가 계산됩니다. 그런 다음 이러한 결과는 벡터 검색 결과와 결합되고 점수별로 순위가 매겨지며 상위 k개로 필터링됩니다.

의미 계층을 테스트하는 가장 쉬운 방법은 Neocarta 저장소에 내장된 CLI 에이전트를 사용하는 것입니다. 임베딩 모델 API 키가유효한 환경 변수 목록run_agent.py 파일에 있습니다. 또한 선택적 MCP 및 에이전트 종속성을 설치해야 합니다.

uv sync --all-groups

또한 원격 BigQuery MCP 서버도 활성화해야 합니다.

gcloud beta services mcp enable bigquery.googleapis.com --project=PROJECT_ID

그리고 gcloud CLI를 통해 로컬에서 인증합니다.

gcloud auth application-default login

그런 다음 명령줄에서 다음 명령어를 실행하세요.

make agent

그러면 로컬 LangGraph 에이전트인 Neocarta MCP 서버가 가동되고 BigQuery 원격 MCP 서버에 연결됩니다.

데모 에이전트를 위한 높은 수준의 아키텍처

또는 Neocarta MCP 서버를 MCP 구성에 추가하여 생성된 의미 계층에 MCP 애플리케이션을 연결할 수 있습니다. 다음은 Neocarta 및 BigQuery MCP 서버를 사용한 Claude Desktop 구성 JSON의 예입니다. 이 방법을 사용하는 경우 BigQuery MCP 서버에 대한 스키마 검색 도구도 사용 중지해야 합니다. Execute_sql 도구만 필요합니다.

참고: 이 구성은 원격 BigQuery MCP 서버가 아닌 Google 도구 상자 SDK의 BigQuery MCP 서버를 사용합니다. 이렇게 하면 인증 구성을 더 쉽게 처리할 수 있습니다.

{
  "mcpServers": {
    "neocarta": {
      "command": "uvx",
      "args": [
        "--from",
        "neocarta[mcp]@0.7.0",
        "neocarta-mcp"
      ],
      "env": {
        "NEO4J_URI": "neo4j+s://xxxxxxxx.databases.neo4j.io",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j",
        "OPENAI_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_DIMENSIONS": "768"
      }
    },
    "bigquery": {
      "command": "npx",
      "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

질문하기

이제 MCP를 통해 의미 체계 계층 및 BigQuery 인스턴스에 에이전트가 연결되었으며 데이터 분석을 시작할 수 있습니다.

참고: 이 응답은 OpenAI gpt-4o-mini를 사용하여 생성되었습니다.

우리는 쉬운 질문으로 시작할 수 있습니다:

총 ARR에 가장 큰 기여를 하는 제품 라인은 무엇이며, 그 분류는 무엇입니까?

이는 구독 및 제품 표를 활용해야 하며 결과는 아래 표 및 요약과 유사합니다.

SELECT
  p.name                                                        AS product,
  COUNT(s.subscription_id)                                      AS active_subscriptions,
  SUM(s.arr_usd)                                                AS arr_usd,
  ROUND(SUM(s.arr_usd) / SUM(SUM(s.arr_usd)) OVER () * 100, 1) AS pct_of_total
FROM acme_corp.subscriptions s
JOIN acme_corp.products p ON s.product_id = p.product_id
WHERE s.status = 'active'
GROUP BY p.name
ORDER BY arr_usd DESC

"Graph DB Enterprise는 Cloud보다 구독 수가 적음에도 불구하고 ARR의 80% 이상을 차지하는 지배적인 수익 원동력입니다. 단일 제품 라인에 대한 이러한 집중은 모니터링해야 할 주요 비즈니스 위험입니다."

이제 조금 더 어려운 질문을 해보겠습니다.

최근 검토 주기에서 성과 평가는 부서 전체에 어떻게 분배되나요?

여기에는performance_reviews, 직원 및 부서의 세 가지 테이블이 필요하며 결과는 다음 통찰력과 유사해야 합니다. 가장 최근 데이터는 2024년 말의 데이터입니다.

SELECT
  d.name           AS department,
  pr.overall_rating,
  COUNT(*)         AS employees,
  ROUND(AVG(pr.numeric_score), 2) AS avg_score
FROM acme_corp.performance_reviews pr
JOIN acme_corp.employees e  ON pr.employee_id  = e.employee_id
JOIN acme_corp.departments d ON e.department_id = d.department_id
WHERE pr.review_period = '2024-H2'
GROUP BY d.name, pr.overall_rating
ORDER BY d.name, pr.overall_rating

"엔지니어링 부문의 성과 분포가 가장 넓습니다. 즉, "초과" 직원 3명이 평균 4.6점, "이하" 직원 1명이 2.4점입니다. 판매 및 제품은 긍정적인 편향을 보입니다. 고객 성공은 검토된 직원이 단 한 명뿐이므로 조사할 데이터 범위 격차가 있음을 시사합니다."

이제 몇 가지 점수를 계산하고 상황에 대한 정보를 추론해야 하는 질문입니다.

고객의 상태 점수와 지원 경험 사이에 상관 관계가 있습니까?

그러면 두 테이블(customers 및 support_tickets)을 조인해야 하며 다음 통찰과 유사한 결과를 얻게 됩니다.

SELECT
  c.company_name                                              AS customer,
  c.segment,
  c.health_score,
  c.status                                                    AS account_status,
  COUNT(t.ticket_id)                                          AS total_tickets,
  ROUND(AVG(t.csat_score), 1)                                 AS avg_csat,
  ROUND(AVG(TIMESTAMP_DIFF(t.resolved_at, t.created_at, HOUR)), 1) AS avg_resolution_hrs
FROM acme_corp.customers c
LEFT JOIN acme_corp.support_tickets t ON c.customer_id = t.customer_id
GROUP BY c.company_name, c.segment, c.health_score, c.status
ORDER BY c.health_score ASC

"상태 점수와 지원 품질 사이에는 분명한 양의 상관 관계가 나타납니다. 이탈한 고객(Umbrella Biotech, 점수 30)은 평가된 모든 티켓 중 가장 낮은 CSAT(3.0)와 가장 긴 해결 시간(49시간)을 기록했습니다. 반대로 가장 높은 점수를 받은 두 고객( Massive Dynamic(95) 및 Globex Financial(87)) 은 완벽한 CSAT 점수와 가장 빠른 해결 시간(2시간 및 49시간)을 기록했습니다. 이는 지원 응답성이 고객 상태의 주요 지표이자 이에 기여한다는 것을 의미합니다. CSAT 점수가 4.0 미만이거나 해결 시간이 30시간 이상인 고객은 적극적인 CSM 지원이 필요합니다."

요약

이 연습에서는 Neocarta Python 라이브러리를 사용하여 Neo4j에서 의미 계층을 구축하는 방법을 시연했습니다. 우리는 BigQuery 스키마 메타데이터와 지식 카탈로그 용어집 정보를 통합하여 데이터 환경에 대한 풍부하고 탐색 가능한 지도를 만들었습니다. 이를 통해 상담원은 상황을 밝게 유지하면서 데이터에 대해 점점 더 복잡해지는 질문에 답할 수 있었습니다.

Neocarta를 사용하는 동안 문제가 발생했거나 기능에 대한 아이디어가 있는 경우 저장소의 GitHub 문제를 제기해 주세요.문제 페이지.

  • AI 에이전트
  • 지식 그래프

에이치시스템즈의 LogTree는 Neo4j 기반 GraphRAG 플랫폼으로, 데이터를 자동으로 지식그래프화하고 자연어 질의로 즉시 답을 제공합니다.

👉 에이치시스템즈 홈페이지

728x90
반응형
저작자표시 비영리 변경금지 (새창열림)

'Agent AI' 카테고리의 다른 글

What 40 AI Agents Revealed About the Future of Graph Intelligence  (0) 2026.07.10
A Tour of the Neo4j Agent Memory Service (NAMS)  (0) 2026.07.08
Neo4j Virtual Graph 출시: 기존 데이터로 그래프 추론을!  (0) 2026.05.29
Building Graph-Based Agentic Systems: Failures, Fixes, and How the Answer Gets There — Part 2  (0) 2026.05.12
Introducing Create Context Graph  (0) 2026.05.08

+ Recent posts

티스토리툴바