BAML을 활용한 비정형 데이터의 Neo4j 그래프 데이터 변환

BAML은 Boundary에서 만든 언어인데요, 구조화되지 않은 데이터로부터 깔끔하고 구조화된 출력을 생성해줘요. 그리고 는 데이터를 그래프, 즉 Nodes와 그 사이의 Relationships로 저장하기 위한 Graph Database랍니다.

이번 기사에서는 BAML의 샘플 프로젝트 중 하나를 확장해서 웹 페이지를 그래프 표현으로 변환하고, Neo4j 인스턴스를 빠르게 채우는 방법을 한번 살펴볼게요.

요구사항

BAML CLI가 설치되어 있어야 해요.
활성 Neo4j Database가 있어야 해요 ().

작업 흐름

1. FastAPI

Boundary에는 간단하게 실행해볼 수 있도록 샘플 코드가 있어요. FastAPI는 브라우저에서 바로 엔드포인트를 테스트할 수 있는 대화형 문서 페이지가 포함된 훌륭한 프레임워크죠.

저는 원래 이걸 포크해서 웹 페이지 콘텐츠에서 엔터티와 Relationships를 추출하기 위한 실험적인 엔드포인트를 추가했어요. 이 엔드포인트는 URL 문자열 목록을 인수로 사용한답니다.

그 다음, 기본 함수는 BAML 함수를 호출해서 웹페이지에서 Neo4j에 업로드된 구조화된 JSON 객체로 데이터를 추출해요.

@app.post("/url_to_graph")
async def extract_url_content(urls: list[str]):
    """General purpose conversion of contents from a list of urls to a graph"""
    
    # 1. Prep html to text conversion
    h = html2text.HTML2Text()
    h.ignore_links = False

    # 2. Extract text from each url
    markdown_contents = []
    for url in urls:
        try:
            response = requests.get(url)
            response.raise_for_status()
            html_content = response.text
            markdown_content = h.handle(html_content)
            markdown_contents.append(markdown_content)
        except Exception as e:
            markdown_contents.append(f"Error processing {url}: {str(e)}")

    # 3. Composite the text 
    combined_markdown = "nn".join(markdown_contents)

    # 4. Run BAML to get a Cytoscape graph JSON representation of text
    json_output = b.GenerateCytoscapeGraph(combined_markdown)
    json_str = str(json_output.model_dump_json())
    json_dict = json.loads(json_str)

    # 5. Upload the JSON data to Neo4j
    finished = upload_cytoscape_to_neo4j(json_dict)
    return {"finished": finished}

2. BAML

구조적으로 BAML을 사용하면 루트 프로젝트 폴더에 baml_src 및 baml_client라는 두 개의 하위 폴더가 추가돼요.

baml_client 폴더의 내용은 활성 Visual Studio(VS) 코드 플러그인에 의해 자동으로 생성되거나, baml_src 폴더의 .baml 파일을 업데이트한 후 `baml cli generate`를 수동으로 실행하면 돼요.

baml_src 폴더에는 main.baml 및 client.baml 파일이 필요한데요, client.baml 파일에는 사용할 기초 모델에 대한 사양이 포함되어 있고 main.baml은 구성 옵션을 지정한답니다.

메모: 여기에 있는 버전 번호는 CLI 버전 또는 자동 버전과 일치해야 해요. baml-client 콘텐츠 생성 작동이 중지될 수 있습니다.

추가하는 .baml 파일에는 다음 세 가지 요소 중 하나 또는 모두가 포함돼요.

BAML 함수는 입력-출력 정의, 사용할 클라이언트 모델 및 LLM 프롬프트를 지정할 수 있는 곳이에요. 다음은 HTML 텍스트를 구조화된 그래프 데이터로 변환하기 위해 FastAPI 엔드포인트가 호출하는 함수입니다.

모델 클래스는 다음과 유사하지만 덜 장황한 방식으로 정의돼요. Pydantic 내부적으로 사용되는 것이죠. 다음과 같은 구조화된 JSON 출력을 얻으려면:

메모:BAML 클래스 및 함수 이름은 다른 .baml 파일에 정의된 경우에도 현재 전역적으로 범위가 지정돼요. 또한 속성 이름에 밑줄이 있는 접두사(예: _id)는 현재 허용되지 않아요.

3. Cytoscape

Cytoscape는 그래프 또는 네트워크 데이터를 시각화하는 데 널리 사용되는 오픈 소스 플랫폼이에요. 사용되는 JSON 데이터 형식은 Node에 필요한 ID 및 Label 속성 외에 추가 데이터를 지원할 수 있을 만큼 간단하면서도 유연하죠.

Neo4j에는 선호되는 JSON 형식이 없고 향후 데모에서 그래프 데이터를 시각화하기 위해 Cytoscape를 사용할 것이기 때문에 중간 그래프 데이터 형식으로 Cytoscape.js를 사용했어요.

4. Neo4j

Neo4j는 가장 널리 사용되는 Graph Database 중 하나에요. 기본적으로는 Cypher 쿼리 언어 그래프 데이터를 입력, 조작, 출력하죠. 따라서 이 데모에서는 공식적으로 지원되는 Neo4j 볼트 파이썬 Cytoscape 형식의 JSON 데이터를 업로드하는 패키지 cytoscape2neo4j.py 파일을 사용합니다.

upload_cytoscape_to_neo4j 함수를 살펴보는 것은 자체 기사를 보장해요. 하지만 간단히 말해서 소스 JSON 데이터에 정의된 각 Node와 Relationship을 반복하고 Cypher 쿼리를 생성하여 지정된 각 Node에 대한 Node와 지정된 각 Edge에 대한 Relationship을 생성합니다.

다음과 같은 OGM(Object Graph Mapper) 패키지 사용 Neomodel, 또는 설정 Apollo GraphQL 서버 JSON과 Neo4j 사이에 이 입력 브리지를 생성하는 대체 방법이에요.

실행

제시된 모든 코드는 여기에서 찾을 수 있어요. 공개 Github 저장소. 그걸 실행하려면 Poetry, 명령줄에서 다음 명령을 실행하세요.

실행하고 나면 브라우저에서 다음 대화형 문서에 액세스할 수 있습니다.로컬호스트:8000/docs:

몇 가지 다른 실험적 종말점이 있지만 여기서 이야기할 것은 /url_to_graph 옵션이에요.

테스트하려면 엔드포인트 세부 정보를 열고 버튼을 클릭한 후 하나 이상의 유효한 URL을 추가한 다음 해 보세요.

잠시 후 소스 웹 페이지의 수와 크기에 따라 완성된:true 응답을 받게 될 거예요.

다음 단계

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

Neo4j v2026.01 (미리보기): 필터와 함께 쓰는 벡터 검색 (1)	2026.06.07
벡터 인덱스와 비정형 데이터 입문 - 새로운 GraphAcademy 강좌 (0)	2026.06.07
스키마의 힘을 깨우다: Python용 Neo4j GraphRAG 패키지의 새로운 기능 (0)	2026.06.06
벡터 검색을 넘어: 더 똑똑한 추천을 위한 GraphRAG의 힘 발휘 (0)	2026.06.06
LightRAG 속살 파헤치기: Retrieval 집중 탐구 (0)	2026.06.06

Graph Note