BAML 是由 Boundary 创建的一种语言，用于从非结构化数据生成干净、结构化的输出。Neo4j 是一种图数据库，用于以图的形式存储数据——包括节点和它们之间的关系。

在本文中，我将演示如何扩展 BAML 的一个示例项目，将网页内容转换为图表示，从而快速填充 Neo4j 实例。

要求

• • 已安装 BAML CLI

• • 一个正在运行的 Neo4j 数据库

工作流程

1. FastAPI

Boundary 提供了运行一个简单 FastAPI 服务器的示例代码，该服务器使用 BAML 从硬编码的简历中提取数据。FastAPI 是一个很棒的框架，包含一个交互式文档页面，可以直接在浏览器中测试端点。

我最初 fork 了这个项目，并添加了一个实验性端点，用于从网页内容中提取实体和关系。这个端点接受一个 URL 字符串列表作为参数。

底层函数会调用 BAML 函数，将网页中的数据提取为结构化的 JSON 对象，并将其上传到 Neo4j。

@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 = "\n\n".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 文件夹的内容可以通过 VS Code 插件自动生成，或者在更新 baml_src 文件夹内的 .baml 文件后手动运行 baml cli generate 命令生成。

baml_src 文件夹需要包含 main.baml 和 clients.baml 文件。clients.baml 文件包括用于基础模型的规范，而 main.baml 指定配置选项。

注意： 这里的版本号应与 CLI 版本匹配，否则自动生成的 baml-client 内容将停止工作。

您添加的 .baml 文件可以包含以下三种元素中的一种或全部：

• • 模型规范（必需）

• • 函数（必需）

• • 测试（可选）

BAML 函数定义了输入到输出的映射、使用的客户端模型以及 LLM 的提示词。以下是 FastAPI 端点调用的函数，用于将 HTML 文本转换为结构化的图数据。

模型类的定义类似于 Pydantic，但语法更简洁（BAML 实际上是基于 Pydantic 的）。要获得如下所示的结构化 JSON 输出：

    {
      "elements": {
        "nodes": [
          {
            "data": {
              "id": "neo4j_graph_database",
              "name": "Neo4j Graph Database",
              "label": "product",
              "description": "Self or fully-managed, deploy anywhere"
            }
          },
          {
            "data": {
              "id": "neo4j_auradb",
              "name": "Neo4j AuraDB",
              "label": "product",
              "description": "Fully-managed graph database as a service"
            }
          },
        ],
        "edges": [
          {
            "data": {
              "id": "edge_1",
              "source": "neo4j_graph_database",
              "target": "neo4j_auradb",
              "label": "RELATED_TO"
            }
          }
        ]
      }
    }

可以使用以下 BAML 中的模型定义：

注意： BAML 类和函数名称在全局范围内是唯一的，即使定义在不同的 .baml 文件中也是如此。此外，属性名称中带有下划线前缀（例如：_id）目前不被允许。

3. Cytoscape

Cytoscape 是一个流行的开源平台，用于可视化图（或网络）数据。它使用的 JSON 数据格式简单但灵活，除了节点所需的 id 和 label 属性外，还支持额外的数据。

前文在 BAML 模型描述中已经展示了这种数据的一个示例。

我使用 Cytoscape.js 作为中间的图数据格式，因为 Neo4j 没有首选的 JSON 格式，而我将在未来的演示中使用 Cytoscape 来可视化图数据。

4. Neo4j

Neo4j 是目前最流行的图数据库之一。它原生使用 Cypher 查询语言来输入、操作和输出图数据。因此，在这个演示中，我使用了官方支持的 neo4j bolt Python 包，在 cytoscape2neo4j.py 文件中上传 Cytoscape 格式的 JSON 数据。

详细讲解 upload_cytoscape_to_neo4j 函数需要单独写一篇文章。但简单来说，它会遍历源 JSON 数据中定义的每个节点和关系，并为每个指定的节点创建一个 Cypher 查询，以及为每条指定的边创建一个关系。

使用对象图映射（OGM）包（例如 Neomodel）或设置 Apollo GraphQL 服务器是创建 JSON 和 Neo4j 之间输入桥接的其他方法。

运行

完整的应用可以在这个公共 Github 仓库中找到。按照安装和运行说明操作后，可以通过任意浏览器访问 localhost:8000/docs 打开交互式文档页面。

还有一些其他的实验性端点，但本文讨论的是 /url_to_graph 选项。

要测试，打开端点详情，点击 Try It Out 按钮（尝试按钮），输入一个或多个有效的网页 URL，然后点击 Execute（执行）。

根据源网页的数量和大小，经过几秒钟后，您应该会收到一个 finished:true 的响应。

在终端/控制台中，您应该会看到类似以下的内容：

    ...
    ---Parsed Response (class CytoscapeJSON)---
    {
      "elements": {
        "nodes": [
          {
            "data": {
              "id": "neo4j_graph_database",
              "name": "Neo4j Graph Database",
              "label": "product",
              "description": "Self or fully-managed, deploy anywhere"
            }
          },
          {
            "data": {
              "id": "neo4j_auradb",
              "name": "Neo4j AuraDB",
              "label": "product",
              "description": "Fully-managed graph database as a service"
            }
          },
          {
            "data": {
              "id": "generative_ai",
              "name": "Generative AI",
              "label": "use_case",
              "description": "Back your LLMs with a knowledge graph for better business AI"
            }
          }
        ],
        "edges": [
          {
            "data": {
              "id": "prod_use_case_1",
              "source": "neo4j_graph_database",
              "target": "generative_ai",
              "label": "ENABLED_BY"
            }
          },
          {
            "data": {
              "id": "prod_use_case_2",
              "source": "neo4j_auradb",
              "target": "generative_ai",
              "label": "ENABLED_BY"
            }
          }
        ]
      }
    }
INFO:     127.0.0.1:63190 - "POST /url_to_graph HTTP/1.1" 200 OK

在您的 Neo4j 控制台中，您应该会看到类似以下的内容：