> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google cloud SQL for mysql 集成

> 使用 LangChain Python 集成 Google Cloud SQL for MySQL 文档加载器。

> [Cloud SQL](https://cloud.google.com/sql) 是一个完全托管的关系型数据库服务，提供高性能、无缝集成和显著的扩展能力。它支持 [MySQL](https://cloud.google.com/sql/mysql)、[PostgreSQL](https://cloud.google.com/sql/postgresql) 和 [SQL Server](https://cloud.google.com/sql/sqlserver) 数据库引擎。利用 Cloud SQL 的 LangChain 集成，扩展您的数据库应用以构建人工智能驱动的体验。

此笔记本将演示如何使用 [Cloud SQL for MySQL](https://cloud.google.com/sql/mysql) 来 [保存、加载和删除 LangChain 文档](https://langchain-docs-zh.mintlify.site/langchain/oss/python/integrations/document_loaders.md)，使用 `MySQLLoader` 和 `MySQLDocumentSaver`。

了解此包的更多信息，请参考 [GitHub](https://github.com/googleapis/langchain-google-cloud-sql-mysql-python/)。

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/googleapis/langchain-google-cloud-sql-mysql-python/blob/main/docs/document_loader.ipynb)

## 开始前

要运行此笔记本，需完成以下步骤：

* [创建 Google Cloud 项目](https://developers.google.com/workspace/guides/create-project)
* [启用 Cloud SQL 管理 API.](https://console.cloud.google.com/marketplace/product/google/sqladmin.googleapis.com)
* [创建 Cloud SQL for MySQL 实例](https://cloud.google.com/sql/docs/mysql/create-instance)
* [创建 Cloud SQL 数据库](https://cloud.google.com/sql/docs/mysql/create-manage-databases)
* [为数据库添加 IAM 数据库用户](https://cloud.google.com/sql/docs/mysql/add-manage-iam-users#creating-a-database-user)（可选）

在笔记本运行环境的数据库访问确认后，填写以下值并运行单元格，再执行示例脚本。

```python theme={null}
# @markdown Please fill in the both the Google Cloud region and name of your Cloud SQL instance.
REGION = "us-central1"  # @param {type:"string"}
INSTANCE = "test-instance"  # @param {type:"string"}

# @markdown Please specify a database and a table for demo purpose.
DATABASE = "test"  # @param {type:"string"}
TABLE_NAME = "test-default"  # @param {type:"string"}
```

### 🦜🔗 库安装

集成位于独立 `langchain-google-cloud-sql-mysql` 包中，需先安装。

```python theme={null}
pip install -upgrade --quiet langchain-google-cloud-sql-mysql
```

**Colab专用**：取消注释以下单元格以重启内核或使用重启按钮。对于 Gemini 企业代理平台工作台，可点击顶部按钮重启终端。

```python theme={null}
# # Automatically restart kernel after installs so that your environment can access the new packages
# import IPython

# app = IPython.Application.instance()
# app.kernel.do_shutdown(True)
```

### ☁ 设置您的 Google 云项目

在此笔记本中设置 Google Cloud 项目以访问云资源。

若不知项目 ID，请：

* 运行 `gcloud config list`。
* 运行 `gcloud projects list`。
* 查看支持页面：[定位项目 ID](https://support.google.com/googleapi/answer/7014113)。

```python theme={null}
# @markdown Please fill in the value below with your Google Cloud project ID and then run the cell.

PROJECT_ID = "my-project-id"  # @param {type:"string"}

# Set the project id
!gcloud config set project {PROJECT_ID}
```

### 🔐 认证

以本笔记本中登录的 IAM 用户身份对 Google Cloud 进行认证以访问项目。

* 若使用 Colab 运行笔记本，请使用下方单元格继续。
* 若使用 Gemini 企业代理平台工作台，请查阅 [Gemini 企业代理平台工作台设置指南](https://github.com/GoogleCloudPlatform/generative-ai/tree/main/setup-env)。

```python theme={null}
from google.colab import auth

auth.authenticate_user()
```

## 基础用法

### MySQLEngine 连接池

在从 MySQL 表保存或加载文档前，需先配置连接池。`MySQLEngine` 用于配置与 Cloud SQL 数据库的连接池，确保应用能成功连接并遵循行业最佳实践。

使用 `MySQLEngine.from_instance()` 创建 `MySQLEngine` 时，需提供以下四项信息：

1. `project_id`：Google Cloud 项目 ID（Cloud SQL 实例所在项目）。
2. `region`：Cloud SQL 实例所在的区域。
3. `instance`：Cloud SQL 实例名称。
4. `database`：要连接的 Cloud SQL 实例数据库名称。

默认使用 [IAM 数据库认证](https://cloud.google.com/sql/docs/mysql/iam-authentication#iam-db-auth) 作为认证方式，库通过环境中的 [应用默认凭据 (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials) 的 IAM 主体进行身份验证。

更多 IAM 数据库认证信息请参考：

* [为实例配置 IAM 数据库认证](https://cloud.google.com/sql/docs/mysql/create-edit-iam-instances)
* [使用 IAM 数据库认证管理用户](https://cloud.google.com/sql/docs/mysql/add-manage-iam-users)

也可选择 [内置数据库认证](https://cloud.google.com/sql/docs/mysql/built-in-authentication)（使用用户名和密码访问数据库），只需提供可选 `user` 和 `password` 参数给 `MySQLEngine.from_instance()`：

* `user`：用于内置认证和登录的数据库用户名
* `password`：用于内置认证和登录的数据库密码

```python theme={null}
from langchain_google_cloud_sql_mysql import MySQLEngine

engine = MySQLEngine.from_instance(
    project_id=PROJECT_ID, region=REGION, instance=INSTANCE, database=DATABASE
)
```

### 初始化表

通过 `MySQLEngine.init_document_table(<table_name>)` 初始化默认架构的表。表列：

* page\_content（类型：text）
* langchain\_metadata（类型：JSON）

`overwrite_existing=True` 标志表示新初始化的表将替换同名现有表。

```python theme={null}
engine.init_document_table(TABLE_NAME, overwrite_existing=True)
```

### 保存文档

使用 `MySQLDocumentSaver.add_documents(<documents>)` 保存 LangChain 文档。初始化 `MySQLDocumentSaver` 类需提供以下两项：

1. `engine`：一个 `MySQLEngine` 引擎实例。
2. `table_name`：Cloud SQL 数据库中用于存储 LangChain 文档的表名。

```python theme={null}
from langchain_core.documents import Document
from langchain_google_cloud_sql_mysql import MySQLDocumentSaver

test_docs = [
    Document(
        page_content="Apple Granny Smith 150 0.99 1",
        metadata={"fruit_id": 1},
    ),
    Document(
        page_content="Banana Cavendish 200 0.59 0",
        metadata={"fruit_id": 2},
    ),
    Document(
        page_content="Orange Navel 80 1.29 1",
        metadata={"fruit_id": 3},
    ),
]
saver = MySQLDocumentSaver(engine=engine, table_name=TABLE_NAME)
saver.add_documents(test_docs)
```

### 加载文档

使用 `MySQLLoader.load()` 或 `MySQLLoader.lazy_load()` 加载 LangChain 文档。`lazy_load` 返回一个仅会在迭代时查询数据库的生成器。初始化 `MySQLLoader` 类需提供以下两项：

1. `engine`：一个 `MySQLEngine` 引擎实例。
2. `table_name`：Cloud SQL 数据库中用于存储 LangChain 文档的表名。

```python theme={null}
from langchain_google_cloud_sql_mysql import MySQLLoader

loader = MySQLLoader(engine=engine, table_name=TABLE_NAME)
docs = loader.lazy_load()
for doc in docs:
    print("Loaded documents:", doc)
```

### 通过查询加载文档

除从表加载文档外，也可通过生成的 SQL 查询视图加载文档。例如：

```python theme={null}
from langchain_google_cloud_sql_mysql import MySQLLoader

loader = MySQLLoader(
    engine=engine,
    query=f"select * from `{TABLE_NAME}` where JSON_EXTRACT(langchain_metadata, '$.fruit_id') = 1;",
)
onedoc = loader.load()
onedoc
```

生成的 SQL 查询视图可能具有与默认表不同的架构。此时，MySQLLoader 的行为与从非默认架构表加载文档相同，请参考 [使用自定义文档内容与元数据加载文档](#使用自定义文档内容与元数据加载文档) 节。

### 删除文档

使用 `MySQLDocumentSaver.delete(<documents>)` 从 MySQL 表删除 LangChain 文档列表。

对于默认架构表（page\_content, langchain\_metadata），删除条件为：\
若存在 `document` 中的一项，满足以下条件则删除 `row`：

* `document.page_content` 等于 `row[page_content]`
* `document.metadata` 等于 `row[langchain_metadata]`

```python theme={null}
from langchain_google_cloud_sql_mysql import MySQLLoader

loader = MySQLLoader(engine=engine, table_name=TABLE_NAME)
docs = loader.load()
print("Documents before delete:", docs)
saver.delete(onedoc)
print("Documents after delete:", loader.load())
```

## 高级用法

### 使用自定义文档内容与元数据加载文档

首先准备一个非默认架构的示例表并填充示例数据。

```python theme={null}
import sqlalchemy

with engine.connect() as conn:
    conn.execute(sqlalchemy.text(f"DROP TABLE IF EXISTS `{TABLE_NAME}`"))
    conn.commit()
    conn.execute(
        sqlalchemy.text(
            f"""
            CREATE TABLE IF NOT EXISTS `{TABLE_NAME}`(
                fruit_id INT AUTO_INCREMENT PRIMARY KEY,
                fruit_name VARCHAR(100) NOT NULL,
                variety VARCHAR(50),
                quantity_in_stock INT NOT NULL,
                price_per_unit DECIMAL(6,2) NOT NULL,
                organic TINYINT(1) NOT NULL
            )
            """
        )
    )
    conn.execute(
        sqlalchemy.text(
            f"""
            INSERT INTO `{TABLE_NAME}` (fruit_name, variety, quantity_in_stock, price_per_unit, organic)
            VALUES
                ('Apple', 'Granny Smith', 150, 0.99, 1),
                ('Banana', 'Cavendish', 200, 0.59, 0),
                ('Orange', 'Navel', 80, 1.29, 1);
            """
        )
    )
    conn.commit()
```

若仍使用 `MySQLLoader` 的默认参数从示例表加载 LangChain 文档，则 `page_content` 将为表第一列，而 `metadata` 将包含其他所有列的键值对。

```python theme={null}
loader = MySQLLoader(
    engine=engine,
    table_name=TABLE_NAME,
)
loader.load()
```

可通过设置 `content_columns` 和 `metadata_columns` 在 `MySQLLoader` 初始化时指定要加载的内容和元数据：

1. `content_columns`：要写入文档 `page_content` 的列
2. `metadata_columns`：要写入文档 `metadata` 的列

例如，`content_columns` 的列值将合并为空格分隔字符串作为 `page_content`，而 `metadata` 将仅包含 `metadata_columns` 中指定的列的键值对。

```python theme={null}
loader = MySQLLoader(
    engine=engine,
    table_name=TABLE_NAME,
    content_columns=[
        "variety",
        "quantity_in_stock",
        "price_per_unit",
        "organic",
    ],
    metadata_columns=["fruit_id", "fruit_name"],
)
loader.load()
```

### 使用自定义内容与元数据保存文档

为了将 langchain 文档保存到具有自定义元数据字段的表格中，我们首先需要通过 `MySQLEngine.init_document_table()` 创建该表格，并指定希望包含的 `metadata_columns` 列表。在此示例中，生成的表格将包含以下列：

* description (类型: text): 用于存储水果描述。
* fruit\_name (类型 text): 用于存储水果名称。
* organic (类型 tinyint(1)): 用于标识水果是否为有机产品。
* other\_metadata (类型: JSON): 用于存储水果的其他元数据信息。

我们可以使用以下 `MySQLEngine.init_document_table()` 参数创建表格：

1. `table_name`: 云 SQL 数据库中用于存储 langchain 文档的表名。
2. `metadata_columns`: 需要的元数据列列表 `sqlalchemy.Column`。
3. `content_column`: 存储 langchain 文档 `page_content` 的列名（默认: `page_content`）。
4. `metadata_json_column`: 存储 langchain 文档额外 `metadata` 的 JSON 列名（默认: `langchain_metadata`）。

```python theme={null}
engine.init_document_table(
    TABLE_NAME,
    metadata_columns=[
        sqlalchemy.Column(
            "fruit_name",
            sqlalchemy.UnicodeText,
            primary_key=False,
            nullable=True,
        ),
        sqlalchemy.Column(
            "organic",
            sqlalchemy.Boolean,
            primary_key=False,
            nullable=True,
        ),
    ],
    content_column="description",
    metadata_json_column="other_metadata",
    overwrite_existing=True,
)
```

使用 `MySQLDocumentSaver.add_documents(<documents>)` 保存文档。如本例所示：

* `document.page_content` 将被保存到 `description` 列。
* `document.metadata.fruit_name` 将被保存到 `fruit_name` 列。
* `document.metadata.organic` 将被保存到 `organic` 列。
* `document.metadata.fruit_id` 将以 JSON 格式保存到 `other_metadata` 列。

```python theme={null}
test_docs = [
    Document(
        page_content="Granny Smith 150 0.99",
        metadata={"fruit_id": 1, "fruit_name": "Apple", "organic": 1},
    ),
]
saver = MySQLDocumentSaver(
    engine=engine,
    table_name=TABLE_NAME,
    content_column="description",
    metadata_json_column="other_metadata",
)
saver.add_documents(test_docs)
```

```python theme={null}
with engine.connect() as conn:
    result = conn.execute(sqlalchemy.text(f"select * from `{TABLE_NAME}`;"))
    print(result.keys())
    print(result.fetchall())
```

### 删除具有自定义页面内容与元数据的文档

我们也可以通过 `MySQLDocumentSaver.delete(<documents>)` 删除具有自定义元数据列的表格中的文档。删除标准如下：

当 `row` 存在 `document` 列表中的某一项时，应删除 `row`：

* `document.page_content` 等于 `row[page_content]`
* 对于 `document.metadata` 中的每个元数据字段 `k`：
  * `document.metadata[k]` 等于 `row[k]` 或 `document.metadata[k]` 等于 `row[langchain_metadata][k]`
* `row` 中不存在 `document.metadata` 但 `row` 中存在 `document.metadata` 的额外元数据字段。

```python theme={null}
loader = MySQLLoader(engine=engine, table_name=TABLE_NAME)
docs = loader.load()
print("Documents before delete:", docs)
saver.delete(docs)
print("Documents after delete:", loader.load())
```

***

> 官方原文：[src/oss/python/integrations/document\_loaders/google\_cloud\_sql\_mysql.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/document_loaders/google_cloud_sql_mysql.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.