diff --git a/docs/blog_posts.zh.md b/docs/blog_posts.zh.md new file mode 100644 index 0000000000..09f895e034 --- /dev/null +++ b/docs/blog_posts.zh.md @@ -0,0 +1,53 @@ +
+ +- [:octicons-arrow-right-24: __GraphRAG：释放 LLM 在叙事型私有数据上的发现能力__](https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/) + + --- +
发布于 2024 年 2 月 13 日 + + 作者：[Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师；[Steven Truitt](https://www.microsoft.com/en-us/research/people/steventruitt/)，首席项目经理
+ + +- [:octicons-arrow-right-24: __GraphRAG：用于复杂数据发现的新工具现已登陆 GitHub__](https://www.microsoft.com/en-us/research/blog/graphrag-new-tool-for-complex-data-discovery-now-on-github/) + + --- +
发布于 2024 年 7 月 2 日 + + 作者：[Darren Edge](https://www.microsoft.com/en-us/research/people/daedge/)，高级总监；[Ha Trinh](https://www.microsoft.com/en-us/research/people/trinhha/)，高级数据科学家；[Steven Truitt](https://www.microsoft.com/en-us/research/people/steventruitt/)，首席项目经理；[Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师
+ + +- [:octicons-arrow-right-24: __GraphRAG 自动调优可快速适应新领域__](https://www.microsoft.com/en-us/research/blog/graphrag-auto-tuning-provides-rapid-adaptation-to-new-domains/) + + --- +
发布于 2024 年 9 月 9 日 + + 作者：[Alonso Guevara Fernández](https://www.microsoft.com/en-us/research/people/alonsog/)，高级软件工程师；Katy Smith，数据科学家 II；[Joshua Bradley](https://www.microsoft.com/en-us/research/people/joshbradley/)，高级数据科学家；[Darren Edge](https://www.microsoft.com/en-us/research/people/daedge/)，高级总监；[Ha Trinh](https://www.microsoft.com/en-us/research/people/trinhha/)，高级数据科学家；[Sarah Smith](https://www.microsoft.com/en-us/research/people/smithsarah/)，高级项目经理；[Ben Cutler](https://www.microsoft.com/en-us/research/people/bcutler/)，高级总监；[Steven Truitt](https://www.microsoft.com/en-us/research/people/steventruitt/)，首席项目经理；[Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师
+ +- [:octicons-arrow-right-24: __介绍 DRIFT Search：结合全局与本地搜索方法以提升质量和效率__](https://www.microsoft.com/en-us/research/blog/introducing-drift-search-combining-global-and-local-search-methods-to-improve-quality-and-efficiency/) + + --- +
发布于 2024 年 10 月 31 日 + + 作者：Julian Whiting，高级机器学习工程师；Zachary Hills ，高级软件工程师；[Alonso Guevara Fernández](https://www.microsoft.com/en-us/research/people/alonsog/)，高级软件工程师；[Ha Trinh](https://www.microsoft.com/en-us/research/people/trinhha/)，高级数据科学家；Adam Bradley ，战略研究管理合伙人；[Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师
+ +- [:octicons-arrow-right-24: __GraphRAG：通过动态社区选择改进全局搜索__](https://www.microsoft.com/en-us/research/blog/graphrag-improving-global-search-via-dynamic-community-selection/) + + --- +
发布于 2024 年 11 月 15 日 + + 作者：Bryan Li，研究实习生；[Ha Trinh](https://www.microsoft.com/en-us/research/people/trinhha/)，高级数据科学家；[Darren Edge](https://www.microsoft.com/en-us/research/people/daedge/)，高级总监；[Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师
+ +- [:octicons-arrow-right-24: __LazyGraphRAG：为质量与成本树立新标准__](https://www.microsoft.com/en-us/research/blog/lazygraphrag-setting-a-new-standard-for-quality-and-cost/) + + --- +
发布于 2024 年 11 月 25 日 + + 作者：[Darren Edge](https://www.microsoft.com/en-us/research/people/daedge/)，高级总监；[Ha Trinh](https://www.microsoft.com/en-us/research/people/trinhha/)，高级数据科学家； [Jonathan Larson](https://www.microsoft.com/en-us/research/people/jolarso/)，高级首席数据架构师
+ +- [:octicons-arrow-right-24: __迈向 GraphRAG 1.0——为开发者和用户简化易用性__](https://www.microsoft.com/en-us/research/blog/moving-to-graphrag-1-0-streamlining-ergonomics-for-developers-and-users) + + --- +
发布于 2024 年 12 月 16 日 + + 作者：[Nathan Evans](https://www.microsoft.com/en-us/research/people/naevans/)，首席软件架构师；[Alonso Guevara Fernández](https://www.microsoft.com/en-us/research/people/alonsog/)，高级软件工程师；[Joshua Bradley](https://www.microsoft.com/en-us/research/people/joshbradley/)，高级数据科学家
+
\ No newline at end of file diff --git a/docs/cli.zh.md b/docs/cli.zh.md new file mode 100644 index 0000000000..820d131822 --- /dev/null +++ b/docs/cli.zh.md @@ -0,0 +1,9 @@ +# CLI 参考 + +本页记录了 graphrag 库的命令行接口。 + +::: mkdocs-typer + :module: graphrag.cli.main + :prog_name: graphrag + :command: app + :depth: 0 \ No newline at end of file diff --git a/docs/config/init.zh.md b/docs/config/init.zh.md new file mode 100644 index 0000000000..411078ec8b --- /dev/null +++ b/docs/config/init.zh.md @@ -0,0 +1,32 @@ +# 配置 GraphRAG 索引 + +要开始使用 GraphRAG，您必须生成一个配置文件。`init` 命令是最简单的入门方式。它将在指定目录中创建 `.env` 和 `settings.yaml` 文件，并包含必要的配置设置。它还会输出 GraphRAG 使用的默认 LLM 提示词。 + +## 用法 + +```sh +graphrag init [--root PATH] [--force, --no-force] +``` + +## 选项 + +- `--root PATH` - 要在其中初始化 graphrag 的项目根目录。默认为当前目录。 +- `--force`, `--no-force` - 可选，默认为 --no-force。如果现有配置文件和提示词文件已存在，则覆盖它们。 + +## 示例 + +```sh +graphrag init --root ./ragtest +``` + +## 输出 + +`init` 命令将在指定目录中创建以下文件： + +- `settings.yaml` - 配置设置文件。此文件包含 GraphRAG 的配置设置。 +- `.env` - 环境变量文件。这些变量会在 `settings.yaml` 文件中被引用。 +- `prompts/` - LLM 提示词文件夹。其中包含 GraphRAG 使用的默认提示词，您可以修改它们，或运行[自动提示词调优](../prompt_tuning/auto_prompt_tuning.md)命令来生成适配您数据的新提示词。 + +## 后续步骤 + +初始化工作区后，您可以运行[提示词调优](../prompt_tuning/auto_prompt_tuning.md)命令以使提示词适配您的数据，或者直接开始运行[索引流水线](../index/overview.md)来为您的数据建立索引。有关可用配置选项的更多信息，请参阅[YAML 详细信息页面](yaml.md)。 \ No newline at end of file diff --git a/docs/config/models.zh.md b/docs/config/models.zh.md new file mode 100644 index 0000000000..c4cfc40764 --- /dev/null +++ b/docs/config/models.zh.md @@ -0,0 +1,115 @@ +# 语言模型选择与覆盖 + +本页包含有关选择要使用的模型以及为 GraphRAG 提供自有模型选项的信息。请注意，这不是关于为你的使用场景寻找合适模型的指南。 + +## 默认模型支持 + +GraphRAG 使用 OpenAI 模型构建并测试，因此这是我们默认支持的模型集。这并不是有意限制，也不是对其质量或是否适合你的使用场景的评价，只是因为这是我们在提示、调优和调试方面最熟悉的一组模型。 + +GraphRAG 使用 [LiteLLM](https://docs.litellm.ai/) 调用语言模型。LiteLLM 提供对 100+ 模型的支持，但需要注意的是，在选择模型时，它必须支持返回遵循 [JSON schema](https://docs.litellm.ai/docs/completion/json_mode) 的[结构化输出](https://openai.com/index/introducing-structured-outputs-in-the-api/)。 + +使用 LiteLLM 作为 GraphRAG 的语言模型管理器的示例： + +```yaml +completion_models: + default_completion_model: + model_provider: gemini + model: gemini-2.5-flash-lite + auth_method: api_key + api_key: ${GEMINI_API_KEY} + +embedding_models: + default_embedding_model: + model_provider: gemini + model: gemini-embedding-001 + auth_method: api_key + api_key: ${GEMINI_API_KEY} +``` + +有关配置的更多详细信息，请参阅 [详细配置](yaml.md)。有关如何调用模型的详细信息，请参阅 [LiteLLM 基本用法](https://docs.litellm.ai/docs/#basic-usage)（`model_provider` 是 `/` 之前的部分，而 `model` 是 `/` 之后的部分）。 + +## 模型选择注意事项 + +GraphRAG 已经使用 OpenAI 的 gpt-4 系列模型进行了最充分的测试，包括 gpt-4、gpt-4-turbo、gpt-4o 和 gpt-4o-mini。例如，我们的 [arXiv 论文](https://arxiv.org/abs/2404.16130) 使用 gpt-4-turbo 进行了质量评估。如上所述，非 OpenAI 模型可通过 LiteLLM 获得支持，但 OpenAI 的 gpt-4 系列模型仍然是 GraphRAG 中测试最充分、支持最完善的一组模型——换句话说，这些是我们最了解、也最能帮助解决相关问题的模型。 + +2.2.0 之前的 GraphRAG 版本大量使用 `max_tokens` 和 `logit_bias` 来控制生成响应的长度或内容。o 系列模型的引入带来了新的、不兼容的参数，因为这些模型包含推理组件，其消耗模式和响应生成特性与非推理模型不同。GraphRAG 2.2.0 现在支持这些模型，但在切换之前，需要先理解一些重要差异。 + +- 以前，GraphRAG 在少数位置使用 `max_tokens` 来限制响应。这是为了在构建下游摘要的上下文窗口时，让内容大小具有可预测性。现在我们已经从使用 `max_tokens` 切换为使用基于提示的方法，并且在测试中效果良好。我们建议仅出于预算原因在你的语言模型配置中使用 `max_tokens`，如果你想限制消耗，而不是用于控制预期响应长度。我们现在也支持 o 系列对应的 `max_completion_tokens`，但如果你使用它，请记住，除了响应 token 之外，可能还存在一些未知的固定推理消耗，因此这并不是控制响应的好技术。 +- 以前，GraphRAG 在 gleanings 期间使用 `max_tokens` 和 `logit_bias` 的组合来严格控制一个二元的 yes/no 问题。这在推理模型中不可行，因此我们再次切换到了基于提示的方法。我们对 gpt-4o、gpt-4o-mini 和 o1 的测试表明这种方法运行稳定，但如果你使用的是较旧或较小的模型，可能会出现问题。 +- o 系列模型更慢且成本更高。在配置中采用非对称的模型使用方式可能会很有帮助：你可以在 `settings.yaml` 的 `models` 块中定义任意数量的模型，并通过键为每个需要语言模型的工作流引用它们。例如，你可以在索引时使用 gpt-4o，在查询时使用 o1。请通过实验找到适合你使用场景的成本、速度和质量平衡点。 +- o 系列模型包含一种原生的 chain-of-thought 推理形式，而非 o 系列模型中没有。GraphRAG 的提示有时包含 CoT，因为这在 gpt-4\* 系列中是一种有效技术。对于 o 系列，这可能适得其反，因此你可能需要调整，甚至重写大部分提示模板（尤其是用于图谱和声明提取的部分）。 + +使用非对称模型的示例配置： + +```yaml +completion_models: + extraction_completion_model: + model_provider: openai + model: gpt-4o + auth_method: api_key + api_key: ${GRAPHRAG_API_KEY} + query_completion_model: + model_provider: openai + model: o1 + auth_method: api_key + api_key: ${GRAPHRAG_API_KEY} +... +extract_graph: + completion_model_id: extraction_completion_model + prompt: "prompts/extract_graph.txt" + entity_types: [organization, person, geo, event] + max_gleanings: 1 +... +global_search: + completion_model_id: query_completion_model + map_prompt: "prompts/global_search_map_system_prompt.txt" + reduce_prompt: "prompts/global_search_reduce_system_prompt.txt" + knowledge_prompt: "prompts/global_search_knowledge_system_prompt.txt" +``` + +另一种选择是在图谱提取中完全不使用语言模型，而是使用 `fast` [索引方法](../index/methods.md)，该方法在索引阶段的部分环节中使用 NLP 来替代 LLM API。 + +## 使用自定义模型 + +LiteLLM 支持数百种模型，但在某些情况下，一些用户仍可能希望使用 LiteLLM 不支持的模型。可使用两种方法连接到不受支持的模型： + +### 代理 API + +许多用户使用诸如 [ollama](https://ollama.com/) 和 [LiteLLM Proxy Server](https://docs.litellm.ai/docs/simple_proxy) 之类的平台，将底层模型 HTTP 调用代理到其他模型提供商。这看起来运行得相当不错，但我们经常看到格式错误的响应问题（尤其是 JSON），因此如果你这样做，请理解你的模型需要能够可靠地返回 GraphRAG 所期望的特定响应格式。如果你在使用某个模型时遇到问题，可能需要尝试通过提示来引导其输出格式，或者在代理内部拦截响应，以尝试处理格式错误的响应。 + +### 模型协议 + +我们支持通过标准 completion 和 embedding Protocol 及其配套工厂来注入模型，你可以使用它们注册你的模型实现。这在 CLI 中不受支持，因此你需要将 GraphRAG 作为库来使用。 + +- 我们的 Protocol [定义在这里](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/completion.py) +- 我们在测试中有一个简单的 mock 实现，你可以[在这里参考](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/mock_llm_completion.py) + +一旦你有了模型实现，就需要将其注册到我们的 completion model factory 或 embedding model factory 中： + +```python +from graphrag_llm.completion import LLMCompletion, register_completion + +class MyCustomCompletionModel(LLMCompletion): + ... + # implementation + +# elsewhere... +register_completion("my-custom-completion-model", MyCustomCompletionModel) +``` + +然后你可以在配置中引用你使用的类型名称： + +```yaml +completion_models: + default_completion_model: + type: my-custom-completion-model + ... + +extract_graph: + completion_model_id: default_completion_model + prompt: "prompts/extract_graph.txt" + entity_types: [organization, person, geo, event] + max_gleanings: 1 +``` + +请注意，你的自定义模型将在初始化和方法调用时接收与我们在整个 GraphRAG 中使用的相同参数。目前还无法定义自定义参数，因此你可能需要在你的实现中使用闭包作用域或工厂模式来获取自定义配置值。 \ No newline at end of file diff --git a/docs/config/overview.zh.md b/docs/config/overview.zh.md new file mode 100644 index 0000000000..8713698137 --- /dev/null +++ b/docs/config/overview.zh.md @@ -0,0 +1,10 @@ +# 配置 GraphRAG 索引 + +GraphRAG 系统具有高度可配置性。本页概述了 GraphRAG 索引引擎可用的配置选项。 + +## 默认配置模式 + +默认配置模式是开始使用 GraphRAG 系统的最简单方式。它旨在以最少的配置开箱即用。以默认配置模式设置 GraphRAG 的主要方式有： + +- [Init 命令](init.md)（推荐的第一步） +- [编辑 settings.yaml 以进行更深入的控制](yaml.md) \ No newline at end of file diff --git a/docs/config/yaml.zh.md b/docs/config/yaml.zh.md new file mode 100644 index 0000000000..4978ddbb24 --- /dev/null +++ b/docs/config/yaml.zh.md @@ -0,0 +1,405 @@ +# 默认配置模式（使用 YAML/JSON） + +默认配置模式可以通过在数据项目根目录中使用 `settings.yml` 或 `settings.json` 文件来配置。如果此配置文件旁边存在 `.env` 文件，则会加载该文件，并且其中定义的环境变量可通过 `${ENV_VAR}` 语法用于配置文档中的令牌替换。我们在 `graphrag init` 中默认使用 YML 进行初始化，但如果你更喜欢，也可以使用等效的 JSON 形式。 + +其中许多配置值都有默认值。与其在此重复列出，请直接参考[代码中的常量](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/config/defaults.py)。 + +例如： + +```bash +# .env +GRAPHRAG_API_KEY=some_api_key + +# settings.yml +default_chat_model: + api_key: ${GRAPHRAG_API_KEY} +``` + +# 配置部分 + +## 语言模型设置 + +### models + +这是一组 dict，一个用于补全模型配置，一个用于嵌入模型配置。dict 的键用于在其他地方需要模型实例时引用模型配置。通过这种方式，你可以根据需要指定任意多个不同的模型，并在工作流步骤中分别引用它们。 + +例如： + +```yml +completion_models: + default_completion_model: + model_provider: openai + model: gpt-4.1 + auth_method: api_key + api_key: ${GRAPHRAG_API_KEY} + +embedding_models: + default_embedding_model: + model_provider: openai + model: text-embedding-3-large + auth_method: api_key + api_key: ${GRAPHRAG_API_KEY} +``` + +#### 字段 + +- `type` **litellm|mock** - 要使用的 LLM 提供程序类型。GraphRAG 使用 [LiteLLM](https://docs.litellm.ai/) 调用语言模型。 +- `model_provider` **str** - 要使用的模型提供程序，例如 openai、azure、anthropic 等。底层使用的是 [LiteLLM](https://docs.litellm.ai/)，它支持调用 100+ 种模型。有关模型如何被调用的详细信息，请参阅 [LiteLLm 基本用法](https://docs.litellm.ai/docs/#basic-usage)（`model_provider` 是 `/` 之前的部分，而 `model` 是 `/` 之后的部分）。有关使用 LiteLLM 的更多细节和示例，请参阅[语言模型选择](models.md)。 +- `model` **str** - 模型名称。 +- `call_args`: **dict[str, Any]** - 随每次模型请求发送的默认参数。例如，`{"n": 5, "max_completion_tokens": 1000, "temperature": 1.5, "organization": "..." }` +- `api_key` **str|None** - 要使用的 OpenAI API 密钥。 +- `api_base` **str|None** - 要使用的 API 基础 url。 +- `api_version` **str|None** - API 版本。 +- `auth_method` **api_key|azure_managed_identity** - 指示你希望如何对请求进行身份验证。 +- `azure_deployment_name` **str|None** - 如果你的模型托管在 Azure 上，要使用的部署名称。请注意，如果你在 Azure 上的部署名称与模型名称匹配，则无需设置此项。 +- retry **RetryConfig|None** - 重试设置。default=`None`，不重试。 + - type **exponential_backoff|immediate** - 重试方式类型。default=`exponential_backoff` + - max_retries **int|None** - 最大重试次数。default=`7`。 + - base_delay **float|None** - 使用 `exponential_backoff` 时的基础延迟。default=`2.0`。 + - jitter **bool|None** - 使用 `exponential_backoff` 时，是否在重试延迟中加入抖动。default=`True` + - max_delay **float|None** - 最大重试延迟。default=`None`，无最大值。 +- rate_limit **RateLimitConfig|None** - 速率限制设置。default=`None`，不进行速率限制。 + - type **sliding_window** - 速率限制方式类型。default=`sliding_window` + - period_in_seconds **int|None** - `sliding_window` 速率限制的窗口大小。default=`60`，即每分钟限制请求数。 + - requests_per_period **int|None** - 每个周期内的最大请求数。default=`None` + - tokens_per_period **int|None** - 每个周期内的最大令牌数。default=`None` +- metrics **MetricsConfig|None** - 指标设置。default=`MetricsConfig()`。有关指标的更多详细信息，请参阅[指标 notebook](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/notebooks/04_metrics.ipynb)。 + - type **default** - 用于处理请求指标的 `MetricsProcessor` 服务类型。default=`default` + - store **memory** - `MetricsStore` 服务类型。default=`memory`。 + - writer **log|file** - 要使用的 `MetricsWriter` 类型。将在流程结束时写出指标。default`log`，在流程结束时使用 python 标准日志记录输出指标。 + - log_level **int|None** - 使用 `log` writer 时的日志级别。default=`20`，为指标记录 `INFO` 消息。 + - base_dir **str|None** - 使用 `file` writer 时写入指标的目录。default=`Path.cwd()`。 + +## 输入文件与分块 + +### input + +我们的流水线可以从输入位置摄取 .csv、.txt 或 .json 数据。有关更多详细信息和示例，请参阅[输入页面](../index/inputs.md)。 + +#### 字段 + +- `storage` **StorageConfig** + - `type` **file|memory|blob|cosmosdb** - 要使用的存储类型。Default=`file` + - `encoding`**str** - 文件存储使用的编码。 + - `base_dir` **str** - 写入输出工件的基础目录，相对于根目录。 + - `connection_string` **str** - （仅 blob/cosmosdb）Azure Storage 连接字符串。 + - `container_name` **str** - （仅 blob/cosmosdb）Azure Storage 容器名称。 + - `account_url` **str** - （仅 blob）要使用的存储帐户 blob URL。 + - `database_name` **str** - （仅 cosmosdb）要使用的数据库名称。 +- `type` **text|csv|json** - 要加载的输入数据类型。默认为 `text` +- `encoding` **str** - 输入文件的编码。默认为 `utf-8` +- `file_pattern` **str** - 用于匹配输入文件的正则表达式。默认值根据指定的 `type` 分别为 `.*\.csv$`、`.*\.txt$` 或 `.*\.json$`，但你可以在需要时自定义它。 +- `id_column` **str** - 要使用的输入 ID 列。 +- `title_column` **str** - 要使用的输入标题列。 +- `text_column` **str** - 要使用的输入文本列。 + +### chunking + +这些设置配置我们如何将文档解析为文本块。这是必要的，因为非常大的文档可能无法放入单个上下文窗口中，并且图提取的准确性可能会受到影响。另请注意输入文档配置中的 `metadata` 设置，它会将文档元数据复制到每个块中。 + +#### 字段 + +- `type` **tokens|sentence** - 要使用的分块类型。 +- `encoding_model` **str** - 用于按令牌边界拆分的文本编码模型。 +- `size` **int** - 以令牌计的最大块大小。 +- `overlap` **int** - 以令牌计的块重叠大小。 +- `prepend_metadata` **list[str]** - 从源文档中提取并预置到每个块前面的元数据字段。 + +## 输出与存储 + +### output + +此部分控制流水线用于导出输出表时所使用的存储机制。 + +#### 字段 + +- `type` **file|memory|blob|cosmosdb** - 要使用的存储类型。Default=`file` +- `encoding`**str** - 文件存储使用的编码。 +- `base_dir` **str** - 写入输出工件的基础目录，相对于根目录。 +- `connection_string` **str** - （仅 blob/cosmosdb）Azure Storage 连接字符串。 +- `container_name` **str** - （仅 blob/cosmosdb）Azure Storage 容器名称。 +- `account_url` **str** - （仅 blob）要使用的存储帐户 blob URL。 +- `database_name` **str** - （仅 cosmosdb）要使用的数据库名称。 +- `type` **text|csv|json** - 要加载的输入数据类型。默认为 `text` +- `encoding` **str** - 输入文件的编码。默认为 `utf-8` + +### update_output_storage + +此部分定义了一个用于运行增量索引的辅助存储位置，以保留你的原始输出。 + +#### 字段 + +- `type` **file|memory|blob|cosmosdb** - 要使用的存储类型。Default=`file` +- `encoding`**str** - 文件存储使用的编码。 +- `base_dir` **str** - 写入输出工件的基础目录，相对于根目录。 +- `connection_string` **str** - （仅 blob/cosmosdb）Azure Storage 连接字符串。 +- `container_name` **str** - （仅 blob/cosmosdb）Azure Storage 容器名称。 +- `account_url` **str** - （仅 blob）要使用的存储帐户 blob URL。 +- `database_name` **str** - （仅 cosmosdb）要使用的数据库名称。 +- `type` **text|csv|json** - 要加载的输入数据类型。默认为 `text` +- `encoding` **str** - 输入文件的编码。默认为 `utf-8` + +### cache + +此部分控制流水线使用的缓存机制。它用于缓存 LLM 调用结果，以便在重新运行索引过程时获得更快的性能。 + +#### 字段 + +- `type` **json|memory|none** - 要使用的存储类型。Default=`json` +- `storage` **StorageConfig** + - `type` **file|memory|blob|cosmosdb** - 要使用的存储类型。Default=`file` + - `encoding`**str** - 文件存储使用的编码。 + - `base_dir` **str** - 写入输出工件的基础目录，相对于根目录。 + - `connection_string` **str** - （仅 blob/cosmosdb）Azure Storage 连接字符串。 + - `container_name` **str** - （仅 blob/cosmosdb）Azure Storage 容器名称。 + - `account_url` **str** - （仅 blob）要使用的存储帐户 blob URL。 + - `database_name` **str** - （仅 cosmosdb）要使用的数据库名称。 + +### reporting + +此部分控制流水线使用的报告机制，用于记录常见事件和错误消息。默认情况下，报告会写入输出目录中的文件。不过，你也可以选择将报告写入 Azure Blob Storage 容器。 + +#### 字段 + +- `type` **file|blob** - 要使用的报告类型。Default=`file` +- `base_dir` **str** - 写入报告的基础目录，相对于根目录。 +- `connection_string` **str** - （仅 blob）Azure Storage 连接字符串。 +- `container_name` **str** - （仅 blob）Azure Storage 容器名称。 +- `account_url` **str** - 要使用的存储帐户 blob URL。 + +### vector_store + +系统中所有向量的存放位置。默认配置为 lancedb。这是一个 dict，其中的键用于标识各个存储参数（例如，用于文本嵌入）。 + +#### 字段 + +- `type` **lancedb|azure_ai_search|cosmosdb** - 向量存储类型。Default=`lancedb` +- `db_uri` **str** (lancedb only) - 数据库 uri。Default=`storage.base_dir/lancedb` +- `url` **str** (blob/cosmosdb only) - 要使用的数据库 / AI Search。 +- `api_key` **str** (optional - AI Search only) - 要使用的 AI Search api 密钥。 +- `audience` **str** (AI Search only) - 如果使用托管身份验证，则为托管身份令牌的受众。 +- `connection_string` **str** - （仅 cosmosdb）Azure Storage 连接字符串。 +- `database_name` **str** - （仅 cosmosdb）数据库名称。 + +- `index_schema` **dict[str, dict[str, str]]** (optional) - 允许你为每种嵌入进行自定义。 + - ``: + - `index_name` **str**: (optional) - 特定嵌入索引表的名称。 + - `id_field` **str**: (optional) - 用作 id 的字段名。Default=`id` + - `vector_field` **str**: (optional) - 用作向量的字段名。Default=`vector` + - `vector_size` **int**: (optional) - 嵌入的向量大小。Default=`3072` + +支持的嵌入有： + +- `text_unit_text` +- `entity_description` +- `community_full_content` + +例如： + +```yaml +vector_store: + type: lancedb + db_uri: output/lancedb + index_schema: + text_unit_text: + index_name: "text-unit-embeddings" + id_field: "id_custom" + vector_field: "vector_custom" + vector_size: 3072 + entity_description: + id_field: "id_custom" +``` + +## 工作流配置 + +这些设置控制每个单独的工作流在执行时的行为。 + +### workflows + +**list[str]** - 这是一个按顺序运行的工作流名称列表。GraphRAG 提供了用于配置此项的内置流水线，但你也可以通过在此指定列表来精确运行你想要且仅想要的内容。如果你已经自行完成了部分处理，这会很有用。 + +### embed_text + +默认情况下，GraphRAG 索引器只会导出查询方法所需的嵌入。不过，模型为所有纯文本字段都定义了嵌入，并且可以通过设置 `target` 和 `names` 字段进行自定义。 + +支持的嵌入名称有： + +- `text_unit_text` +- `entity_description` +- `community_full_content` + +#### 字段 + +- `embedding_model_id` **str** - 用于文本嵌入的模型定义名称。 +- `model_instance_name` **str** - 模型单例实例的名称。默认值为 "text_embedding"。这主要影响缓存存储分区。 +- `batch_size` **int** - 要使用的最大批大小。 +- `batch_max_tokens` **int** - 每批的最大令牌数。 +- `names` **list[str]** - 要运行的嵌入名称列表（必须在支持列表中）。 + +### extract_graph + +调整基于语言模型的图提取过程。 + +#### 字段 + +- `completion_model_id` **str** - 用于 API 调用的模型定义名称。 +- `model_instance_name` **str** - 模型单例实例的名称。默认值为 "extract_graph"。这主要影响缓存存储分区。 +- `prompt` **str** - 要使用的提示文件。 +- `entity_types` **list[str]** - 要识别的实体类型。 +- `max_gleanings` **int** - 要使用的最大提炼循环次数。 + +### summarize_descriptions + +#### 字段 + +- `completion_model_id` **str** - 用于 API 调用的模型定义名称。 +- `model_instance_name` **str** - 模型单例实例的名称。默认值为 "summarize_descriptions"。这主要影响缓存存储分区。 +- `prompt` **str** - 要使用的提示文件。 +- `max_length` **int** - 每次摘要输出的最大令牌数。 +- `max_input_length` **int** - 用于摘要的最大收集令牌数（这将限制你为给定实体或关系发送进行摘要的描述数量）。 + +### extract_graph_nlp + +定义基于 NLP 的图提取方法设置。 + +#### 字段 + +- `normalize_edge_weights` **bool** - 是否在图构建期间对边权重进行归一化。Default=`True`。 +- `concurrent_requests` **int** - 提取过程中使用的线程数。 +- `async_mode` **asyncio|threaded** - 要使用的异步模式。可以是 `asyncio` 或 `threaded`。 +- `text_analyzer` **dict** - NLP 模型的参数。 + - `extractor_type` **regex_english|syntactic_parser|cfg** - Default=`regex_english`。 + - `model_name` **str** - NLP 模型名称（用于基于 SpaCy 的模型） + - `max_word_length` **int** - 允许的最长单词长度。Default=`15`。 + - `word_delimiter` **str** - 用于拆分单词的分隔符。默认值为 `' '`。 + - `include_named_entities` **bool** - 是否在名词短语中包含命名实体。Default=`True`。 + - `exclude_nouns` **list[str] | None** - 要排除的名词列表。如果为 `None`，我们将使用内部停用词列表。 + - `exclude_entity_tags` **list[str]** - 要忽略的实体标签列表。 + - `exclude_pos_tags` **list[str]** - 要忽略的词性标签列表。 + - `noun_phrase_tags` **list[str]** - 要忽略的名词短语标签列表。 + - `noun_phrase_grammars` **dict[str, str]** - 该模型的名词短语语法（仅 cfg）。 + +### prune_graph + +手动图修剪的参数。这可用于通过移除连接过多或过于罕见的节点来优化图聚类的模块度。 + +#### 字段 + +- `min_node_freq` **int** - 允许的最小节点频率。 +- `max_node_freq_std` **float | None** - 允许的最大节点频率标准差。 +- `min_node_degree` **int** - 允许的最小节点度。 +- `max_node_degree_std` **float | None** - 允许的最大节点度标准差。 +- `min_edge_weight_pct` **float** - 允许的最小边权重百分位数。 +- `remove_ego_nodes` **bool** - 移除自我中心节点。 +- `lcc_only` **bool** - 仅使用最大连通分量。 + +### cluster_graph + +这些设置用于对图执行 Leiden 分层聚类以创建社区。 + +#### 字段 + +- `max_cluster_size` **int** - 要导出的最大聚类大小。 +- `use_lcc` **bool** - 是否仅使用最大连通分量。 +- `seed` **int** - 如果希望每次运行结果一致，则提供一个随机种子。我们确实提供了一个默认值，以保证聚类稳定性。 + +### extract_claims + +#### 字段 + +- `enabled` **bool** - 是否启用声明提取。默认关闭，因为声明提示确实需要用户进行调优。 +- `completion_model_id` **str** - 用于 API 调用的模型定义名称。 +- `model_instance_name` **str** - 模型单例实例的名称。默认值为 "extract_claims"。这主要影响缓存存储分区。 +- `prompt` **str** - 要使用的提示文件。 +- `description` **str** - 描述我们想要提取的声明类型。 +- `max_gleanings` **int** - 要使用的最大提炼循环次数。 + +### community_reports + +#### 字段 + +- `completion_model_id` **str** - 用于 API 调用的模型定义名称。 +- `model_instance_name` **str** - 模型单例实例的名称。默认值为 "community_reporting"。这主要影响缓存存储分区。 +- `graph_prompt` **str | None** - 用于基于图的摘要的社区报告提取提示。 +- `text_prompt` **str | None** - 用于基于文本的摘要的社区报告提取提示。 +- `max_length` **int** - 每份报告的最大输出令牌数。 +- `max_input_length` **int** - 生成报告时可使用的最大输入令牌数。 + +### snapshots + +#### 字段 + +- `embeddings` **bool** - 将嵌入快照导出为 parquet。 +- `graphml` **bool** - 将图快照导出为 GraphML。 +- `raw_graph` **bool** - 在合并前导出原始提取图。 + +## 查询 + +### local_search + +#### 字段 + +- `prompt` **str** - 要使用的提示文件。 +- `completion_model_id` **str** - 用于 Chat Completion 调用的模型定义名称。 +- `embedding_model_id` **str** - 用于 Embedding 调用的模型定义名称。 +- `text_unit_prop` **float** - 文本单元比例。 +- `community_prop` **float** - 社区比例。 +- `conversation_history_max_turns` **int** - 对话历史的最大轮数。 +- `top_k_entities` **int** - 映射到的前 k 个实体。 +- `top_k_relationships` **int** - 映射到的前 k 个关系。 +- `max_context_tokens` **int** - 构建请求上下文时可使用的最大令牌数。 + +### global_search + +#### 字段 + +- `map_prompt` **str** - 要使用的全局搜索 mapper 提示。 +- `reduce_prompt` **str** - 要使用的全局搜索 reducer。 +- `completion_model_id` **str** - 用于 Chat Completion 调用的模型定义名称。 +- `knowledge_prompt` **str** - 要使用的知识提示文件。 +- `data_max_tokens` **int** - 用于根据 reduce 响应构建最终响应时可使用的最大令牌数。 +- `map_max_length` **int** - map 响应请求的最大长度，以单词计。 +- `reduce_max_length` **int** - reduce 响应请求的最大长度，以单词计。 +- `dynamic_search_threshold` **int** - 包含社区报告的评分阈值。 +- `dynamic_search_keep_parent` **bool** - 如果任一子社区相关，则保留父社区。 +- `dynamic_search_num_repeats` **int** - 对同一社区报告进行评分的次数。 +- `dynamic_search_use_summary` **bool** - 使用社区摘要而不是 full_context。 +- `dynamic_search_max_level` **int** - 如果已处理的社区都不相关，则要考虑的社区层级最大级别。 + +### drift_search + +#### 字段 + +- `prompt` **str** - 要使用的提示文件。 +- `reduce_prompt` **str** - 要使用的 reducer 提示文件。 +- `completion_model_id` **str** - 用于 Chat Completion 调用的模型定义名称。 +- `embedding_model_id` **str** - 用于 Embedding 调用的模型定义名称。 +- `data_max_tokens` **int** - 数据 llm 的最大令牌数。 +- `reduce_max_tokens` **int** - reduce 阶段的最大令牌数。仅在非 o-series 模型中使用。 +- `reduce_temperature` **float** - 在 reduce 中用于令牌生成的 temperature。 +- `reduce_max_completion_tokens` **int** - reduce 阶段的最大令牌数。仅用于 o-series 模型。 +- `concurrency` **int** - 并发请求数。 +- `drift_k_followups` **int** - 要检索的顶级全局结果数量。 +- `primer_folds` **int** - 搜索预热的折数。 +- `primer_llm_max_tokens` **int** - primer 中 LLM 的最大令牌数。 +- `n_depth` **int** - 要执行的 drift search 步数。 +- `local_search_text_unit_prop` **float** - 分配给文本单元的搜索比例。 +- `local_search_community_prop` **float** - 分配给社区属性的搜索比例。 +- `local_search_top_k_mapped_entities` **int** - 本地搜索期间要映射的前 K 个实体数量。 +- `local_search_top_k_relationships` **int** - 本地搜索期间要映射的前 K 个关系数量。 +- `local_search_max_data_tokens` **int** - 本地搜索的最大上下文大小（以令牌计）。 +- `local_search_temperature` **float** - 本地搜索中用于令牌生成的 temperature。 +- `local_search_top_p` **float** - 本地搜索中用于令牌生成的 top-p 值。 +- `local_search_n` **int** - 本地搜索中要生成的补全数量。 +- `local_search_llm_max_gen_tokens` **int** - 本地搜索中 LLM 的最大生成令牌数。仅在非 o-series 模型中使用。 +- `local_search_llm_max_gen_completion_tokens` **int** - 本地搜索中 LLM 的最大生成令牌数。仅用于 o-series 模型。 + +### basic_search + +#### 字段 + +- `prompt` **str** - 要使用的提示文件。 +- `completion_model_id` **str** - 用于 Chat Completion 调用的模型定义名称。 +- `embedding_model_id` **str** - 用于 Embedding 调用的模型定义名称。 +- `k` **int** - 为构建上下文而从向量存储中检索的文本单元数量。 +- `max_context_tokens` **int** - 要创建的最大上下文大小，以令牌计。 \ No newline at end of file diff --git a/docs/data/operation_dulce/ABOUT.zh.md b/docs/data/operation_dulce/ABOUT.zh.md new file mode 100644 index 0000000000..b0d073ab97 --- /dev/null +++ b/docs/data/operation_dulce/ABOUT.zh.md @@ -0,0 +1,3 @@ +# 关于 + +本文档（Operation Dulce）是一部由 AI 生成的科幻中篇小说，包含于此是为了进行集成测试。 \ No newline at end of file diff --git a/docs/developing.zh.md b/docs/developing.zh.md new file mode 100644 index 0000000000..f64945a9f2 --- /dev/null +++ b/docs/developing.zh.md @@ -0,0 +1,75 @@ +# 开发指南 + +# 要求 + +| Name | Installation | Purpose | +| ------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| Python 3.10-3.12 | [Download](https://www.python.org/downloads/) | 该库基于 Python。 | +| uv | [Instructions](https://docs.astral.sh/uv/) | uv 用于 Python 代码库中的包管理和虚拟环境管理 | + +# 入门 + +## 安装依赖 + +```sh +# 安装 python 依赖 +uv sync --all-packages +``` + +## 执行索引引擎 + +```sh +uv run poe index <...args> +``` + +## 执行查询 + +```sh +uv run poe query <...args> +``` + +# Azurite + +一些单元测试和冒烟测试使用 Azurite 来模拟 Azure 资源。可以通过运行以下命令启动： + +```sh +./scripts/start-azurite.sh +``` + +或者，如果已全局安装，也可以直接在终端中运行 `azurite`。有关如何安装和使用 Azurite 的更多信息，请参阅 [Azurite documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite)。 + +# 生命周期脚本 + +我们的 Python 包使用 uv 管理依赖，并使用 [poethepoet](https://pypi.org/project/poethepoet/) 管理构建脚本。 + +可用脚本包括： + +- `uv run poe index` - 运行索引 CLI +- `uv run poe query` - 运行查询 CLI +- `uv build` - 这将构建 wheel 文件和其他可分发工件。 +- `uv run poe test` - 这将执行所有测试。 +- `uv run poe test_unit` - 这将执行单元测试。 +- `uv run poe test_integration` - 这将执行集成测试。 +- `uv run poe test_smoke` - 这将执行冒烟测试。 +- `uv run poe test_verbs` - 这将执行基本工作流测试。 +- `uv run poe check` - 这将对整个包执行一组静态检查，包括： + - 格式化 + - 文档格式化 + - lint 检查 + - 安全模式 + - 类型检查 +- `uv run poe fix` - 这将对整个包应用所有可用的自动修复。通常这只是格式修复。 +- `uv run poe fix_unsafe` - 这将对整个包应用所有可用的自动修复，包括可能不安全的修复。 +- `uv run poe format` - 显式对整个包运行格式化工具。 + +## 故障排除 + +### 运行 uv install 时出现 “RuntimeError: llvm-config failed executing, please point LLVM_CONFIG to the path for llvm-config” + +请确保已安装 llvm-9 和 llvm-9-dev： + +`sudo apt-get install llvm-9 llvm-9-dev` + +然后在你的 bashrc 中添加 + +`export LLVM_CONFIG=/usr/bin/llvm-config-9` \ No newline at end of file diff --git a/docs/examples_notebooks/drift_search.zh.ipynb b/docs/examples_notebooks/drift_search.zh.ipynb new file mode 100644 index 0000000000..8d53c7d9cc --- /dev/null +++ b/docs/examples_notebooks/drift_search.zh.ipynb @@ -0,0 +1,210 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Copyright (c) 2024 Microsoft Corporation.\n", + "# Licensed under the MIT License." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "from graphrag.config.enums import ModelType\n", + "from graphrag.config.models.drift_search_config import DRIFTSearchConfig\n", + "from graphrag.config.models.language_model_config import LanguageModelConfig\n", + "from graphrag.language_model.manager import ModelManager\n", + "from graphrag.query.indexer_adapters import (\n", + " read_indexer_entities,\n", + " read_indexer_relationships,\n", + " read_indexer_report_embeddings,\n", + " read_indexer_reports,\n", + " read_indexer_text_units,\n", + ")\n", + "from graphrag.query.structured_search.drift_search.drift_context import (\n", + " DRIFTSearchContextBuilder,\n", + ")\n", + "from graphrag.query.structured_search.drift_search.search import DRIFTSearch\n", + "from graphrag.tokenizer.get_tokenizer import get_tokenizer\n", + "from graphrag_vectors.lancedb import LanceDBVectorStore\n", + "\n", + "INPUT_DIR = \"./inputs/operation dulce\"\n", + "LANCEDB_URI = f\"{INPUT_DIR}/lancedb\"\n", + "\n", + "COMMUNITY_REPORT_TABLE = \"community_reports\"\n", + "COMMUNITY_TABLE = \"communities\"\n", + "ENTITY_TABLE = \"entities\"\n", + "RELATIONSHIP_TABLE = \"relationships\"\n", + "COVARIATE_TABLE = \"covariates\"\n", + "TEXT_UNIT_TABLE = \"text_units\"\n", + "COMMUNITY_LEVEL = 2\n", + "\n", + "\n", + "# read nodes table to get community and degree data\n", + "entity_df = pd.read_parquet(f\"{INPUT_DIR}/{ENTITY_TABLE}.parquet\")\n", + "community_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet\")\n", + "\n", + "print(f\"Entity df columns: {entity_df.columns}\")\n", + "\n", + "entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)\n", + "\n", + "# load description embeddings to an in-memory lancedb vectorstore\n", + "# to connect to a remote db, specify url and port values.\n", + "description_embedding_store = LanceDBVectorStore(\n", + " db_uri=LANCEDB_URI,\n", + " index_name=\"entity_description\",\n", + ")\n", + "description_embedding_store.connect()\n", + "\n", + "full_content_embedding_store = LanceDBVectorStore(\n", + " db_uri=LANCEDB_URI,\n", + " index_name=\"community_full_content\",\n", + ")\n", + "full_content_embedding_store.connect()\n", + "\n", + "print(f\"Entity count: {len(entity_df)}\")\n", + "entity_df.head()\n", + "\n", + "relationship_df = pd.read_parquet(f\"{INPUT_DIR}/{RELATIONSHIP_TABLE}.parquet\")\n", + "relationships = read_indexer_relationships(relationship_df)\n", + "\n", + "print(f\"Relationship count: {len(relationship_df)}\")\n", + "relationship_df.head()\n", + "\n", + "text_unit_df = pd.read_parquet(f\"{INPUT_DIR}/{TEXT_UNIT_TABLE}.parquet\")\n", + "text_units = read_indexer_text_units(text_unit_df)\n", + "\n", + "print(f\"Text unit records: {len(text_unit_df)}\")\n", + "text_unit_df.head()\n", + "\n", + "report_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_REPORT_TABLE}.parquet\")\n", + "reports = read_indexer_reports(report_df, community_df, COMMUNITY_LEVEL)\n", + "read_indexer_report_embeddings(reports, full_content_embedding_store)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "api_key = os.environ[\"GRAPHRAG_API_KEY\"]\n", + "\n", + "chat_config = LanguageModelConfig(\n", + " api_key=api_key,\n", + " type=ModelType.Chat,\n", + " model_provider=\"openai\",\n", + " model=\"gpt-4.1\",\n", + " max_retries=20,\n", + ")\n", + "chat_model = ModelManager().get_or_create_chat_model(\n", + " name=\"local_search\",\n", + " model_type=ModelType.Chat,\n", + " config=chat_config,\n", + ")\n", + "\n", + "tokenizer = get_tokenizer(chat_config)\n", + "\n", + "embedding_config = LanguageModelConfig(\n", + " api_key=api_key,\n", + " type=ModelType.Embedding,\n", + " model_provider=\"openai\",\n", + " model=\"text-embedding-3-large\",\n", + " max_retries=20,\n", + ")\n", + "\n", + "text_embedder = ModelManager().get_or_create_embedding_model(\n", + " name=\"local_search_embedding\",\n", + " model_type=ModelType.Embedding,\n", + " config=embedding_config,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "drift_params = DRIFTSearchConfig(\n", + " primer_folds=1,\n", + " drift_k_followups=3,\n", + " n_depth=3,\n", + ")\n", + "\n", + "context_builder = DRIFTSearchContextBuilder(\n", + " model=chat_model,\n", + " text_embedder=text_embedder,\n", + " entities=entities,\n", + " relationships=relationships,\n", + " reports=reports,\n", + " entity_text_embeddings=description_embedding_store,\n", + " text_units=text_units,\n", + " tokenizer=tokenizer,\n", + " config=drift_params,\n", + ")\n", + "\n", + "search = DRIFTSearch(\n", + " model=chat_model, context_builder=context_builder, tokenizer=tokenizer\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "resp = await search.search(\"Who is agent Mercer?\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "resp.response" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "print(resp.context_data)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.10" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples_notebooks/global_search.zh.ipynb b/docs/examples_notebooks/global_search.zh.ipynb new file mode 100644 index 0000000000..605f704bd2 --- /dev/null +++ b/docs/examples_notebooks/global_search.zh.ipynb @@ -0,0 +1,262 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Copyright (c) 2024 Microsoft Corporation.\n", + "# Licensed under the MIT License." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "from graphrag.config.enums import ModelType\n", + "from graphrag.config.models.language_model_config import LanguageModelConfig\n", + "from graphrag.language_model.manager import ModelManager\n", + "from graphrag.query.indexer_adapters import (\n", + " read_indexer_communities,\n", + " read_indexer_entities,\n", + " read_indexer_reports,\n", + ")\n", + "from graphrag.query.structured_search.global_search.community_context import (\n", + " GlobalCommunityContext,\n", + ")\n", + "from graphrag.query.structured_search.global_search.search import GlobalSearch\n", + "from graphrag.tokenizer.get_tokenizer import get_tokenizer" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Global Search example\n", + "\n", + "Global search method generates answers by searching over all AI-generated community reports in a map-reduce fashion. This is a resource-intensive method, but often gives good responses for questions that require an understanding of the dataset as a whole (e.g. What are the most significant values of the herbs mentioned in this notebook?)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### LLM setup" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "api_key = os.environ[\"GRAPHRAG_API_KEY\"]\n", + "\n", + "config = LanguageModelConfig(\n", + " api_key=api_key,\n", + " type=ModelType.Chat,\n", + " model_provider=\"openai\",\n", + " model=\"gpt-4.1\",\n", + " max_retries=20,\n", + ")\n", + "model = ModelManager().get_or_create_chat_model(\n", + " name=\"global_search\",\n", + " model_type=ModelType.Chat,\n", + " config=config,\n", + ")\n", + "\n", + "tokenizer = get_tokenizer(config)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Load community reports as context for global search\n", + "\n", + "- Load all community reports in the `community_reports` table from GraphRAG, to be used as context data for global search.\n", + "- Load entities from the `entities` tables from GraphRAG, to be used for calculating community weights for context ranking. Note that this is optional (if no entities are provided, we will not calculate community weights and only use the rank attribute in the community reports table for context ranking)\n", + "- Load all communities in the `communities` table from the GraphRAG, to be used to reconstruct the community graph hierarchy for dynamic community selection." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# parquet files generated from indexing pipeline\n", + "INPUT_DIR = \"./inputs/operation dulce\"\n", + "COMMUNITY_TABLE = \"communities\"\n", + "COMMUNITY_REPORT_TABLE = \"community_reports\"\n", + "ENTITY_TABLE = \"entities\"\n", + "\n", + "# community level in the Leiden community hierarchy from which we will load the community reports\n", + "# higher value means we use reports from more fine-grained communities (at the cost of higher computation cost)\n", + "COMMUNITY_LEVEL = 2" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "community_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet\")\n", + "entity_df = pd.read_parquet(f\"{INPUT_DIR}/{ENTITY_TABLE}.parquet\")\n", + "report_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_REPORT_TABLE}.parquet\")\n", + "\n", + "communities = read_indexer_communities(community_df, report_df)\n", + "reports = read_indexer_reports(report_df, community_df, COMMUNITY_LEVEL)\n", + "entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)\n", + "\n", + "print(f\"Total report count: {len(report_df)}\")\n", + "print(\n", + " f\"Report count after filtering by community level {COMMUNITY_LEVEL}: {len(reports)}\"\n", + ")\n", + "\n", + "report_df.head()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Build global context based on community reports" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "context_builder = GlobalCommunityContext(\n", + " community_reports=reports,\n", + " communities=communities,\n", + " entities=entities, # default to None if you don't want to use community weights for ranking\n", + " tokenizer=tokenizer,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Perform global search" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "context_builder_params = {\n", + " \"use_community_summary\": False, # False means using full community reports. True means using community short summaries.\n", + " \"shuffle_data\": True,\n", + " \"include_community_rank\": True,\n", + " \"min_community_rank\": 0,\n", + " \"community_rank_name\": \"rank\",\n", + " \"include_community_weight\": True,\n", + " \"community_weight_name\": \"occurrence weight\",\n", + " \"normalize_community_weight\": True,\n", + " \"max_tokens\": 12_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000)\n", + " \"context_name\": \"Reports\",\n", + "}\n", + "\n", + "map_llm_params = {\n", + " \"max_tokens\": 1000,\n", + " \"temperature\": 0.0,\n", + " \"response_format\": {\"type\": \"json_object\"},\n", + "}\n", + "\n", + "reduce_llm_params = {\n", + " \"max_tokens\": 2000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 1000-1500)\n", + " \"temperature\": 0.0,\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "search_engine = GlobalSearch(\n", + " model=model,\n", + " context_builder=context_builder,\n", + " tokenizer=tokenizer,\n", + " max_data_tokens=12_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000)\n", + " map_llm_params=map_llm_params,\n", + " reduce_llm_params=reduce_llm_params,\n", + " allow_general_knowledge=False, # set this to True will add instruction to encourage the LLM to incorporate general knowledge in the response, which may increase hallucinations, but could be useful in some use cases.\n", + " json_mode=True, # set this to False if your LLM model does not support JSON mode.\n", + " context_builder_params=context_builder_params,\n", + " concurrent_coroutines=32,\n", + " response_type=\"multiple paragraphs\", # free form text describing the response type and format, can be anything, e.g. prioritized list, single paragraph, multiple paragraphs, multiple-page report\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result = await search_engine.search(\"What is operation dulce?\")\n", + "\n", + "print(result.response)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# inspect the data used to build the context for the LLM responses\n", + "result.context_data[\"reports\"]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# inspect number of LLM calls and tokens\n", + "print(\n", + " f\"LLM calls: {result.llm_calls}. Prompt tokens: {result.prompt_tokens}. Output tokens: {result.output_tokens}.\"\n", + ")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "graphrag", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.10" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/examples_notebooks/inputs/operation dulce/ABOUT.zh.md b/docs/examples_notebooks/inputs/operation dulce/ABOUT.zh.md new file mode 100644 index 0000000000..c94a91e773 --- /dev/null +++ b/docs/examples_notebooks/inputs/operation dulce/ABOUT.zh.md @@ -0,0 +1,3 @@ +# 关于 + +本文档（Operation Dulce）是一部由 AI 生成的科幻中篇小说，包含于此旨在为 notebook 实验提供一个起点。 \ No newline at end of file diff --git a/docs/examples_notebooks/local_search.zh.ipynb b/docs/examples_notebooks/local_search.zh.ipynb new file mode 100644 index 0000000000..f7f0c5a54b --- /dev/null +++ b/docs/examples_notebooks/local_search.zh.ipynb @@ -0,0 +1,472 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Copyright (c) 2024 Microsoft Corporation.\n", + "# Licensed under the MIT License." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "from graphrag.query.context_builder.entity_extraction import EntityVectorStoreKey\n", + "from graphrag.query.indexer_adapters import (\n", + " read_indexer_covariates,\n", + " read_indexer_entities,\n", + " read_indexer_relationships,\n", + " read_indexer_reports,\n", + " read_indexer_text_units,\n", + ")\n", + "from graphrag.query.question_gen.local_gen import LocalQuestionGen\n", + "from graphrag.query.structured_search.local_search.mixed_context import (\n", + " LocalSearchMixedContext,\n", + ")\n", + "from graphrag.query.structured_search.local_search.search import LocalSearch\n", + "from graphrag_vectors import IndexSchema, LanceDBVectorStore" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Local Search Example\n", + "\n", + "Local search method generates answers by combining relevant data from the AI-extracted knowledge-graph with text chunks of the raw documents. This method is suitable for questions that require an understanding of specific entities mentioned in the documents (e.g. What are the healing properties of chamomile?)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Load text units and graph data tables as context for local search\n", + "\n", + "- In this test we first load indexing outputs from parquet files to dataframes, then convert these dataframes into collections of data objects aligning with the knowledge model." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Load tables to dataframes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "INPUT_DIR = \"./inputs/operation dulce\"\n", + "LANCEDB_URI = f\"{INPUT_DIR}/lancedb\"\n", + "\n", + "COMMUNITY_REPORT_TABLE = \"community_reports\"\n", + "ENTITY_TABLE = \"entities\"\n", + "COMMUNITY_TABLE = \"communities\"\n", + "RELATIONSHIP_TABLE = \"relationships\"\n", + "COVARIATE_TABLE = \"covariates\"\n", + "TEXT_UNIT_TABLE = \"text_units\"\n", + "COMMUNITY_LEVEL = 2" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Read entities" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# read nodes table to get community and degree data\n", + "entity_df = pd.read_parquet(f\"{INPUT_DIR}/{ENTITY_TABLE}.parquet\")\n", + "community_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_TABLE}.parquet\")\n", + "\n", + "entities = read_indexer_entities(entity_df, community_df, COMMUNITY_LEVEL)\n", + "\n", + "# load description embeddings to an in-memory lancedb vectorstore\n", + "# to connect to a remote db, specify url and port values.\n", + "description_embedding_store = LanceDBVectorStore(\n", + " index_schema=IndexSchema(index_name=\"default-entity-description\")\n", + ")\n", + "description_embedding_store.connect(db_uri=LANCEDB_URI)\n", + "\n", + "print(f\"Entity count: {len(entity_df)}\")\n", + "entity_df.head()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Read relationships" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "relationship_df = pd.read_parquet(f\"{INPUT_DIR}/{RELATIONSHIP_TABLE}.parquet\")\n", + "relationships = read_indexer_relationships(relationship_df)\n", + "\n", + "print(f\"Relationship count: {len(relationship_df)}\")\n", + "relationship_df.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# NOTE: covariates are turned off by default, because they generally need prompt tuning to be valuable\n", + "# Please see the GRAPHRAG_CLAIM_* settings\n", + "covariate_df = pd.read_parquet(f\"{INPUT_DIR}/{COVARIATE_TABLE}.parquet\")\n", + "\n", + "claims = read_indexer_covariates(covariate_df)\n", + "\n", + "print(f\"Claim records: {len(claims)}\")\n", + "covariates = {\"claims\": claims}" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Read community reports" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "report_df = pd.read_parquet(f\"{INPUT_DIR}/{COMMUNITY_REPORT_TABLE}.parquet\")\n", + "reports = read_indexer_reports(report_df, community_df, COMMUNITY_LEVEL)\n", + "\n", + "print(f\"Report records: {len(report_df)}\")\n", + "report_df.head()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Read text units" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "text_unit_df = pd.read_parquet(f\"{INPUT_DIR}/{TEXT_UNIT_TABLE}.parquet\")\n", + "text_units = read_indexer_text_units(text_unit_df)\n", + "\n", + "print(f\"Text unit records: {len(text_unit_df)}\")\n", + "text_unit_df.head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from graphrag.config.enums import ModelType\n", + "from graphrag.config.models.language_model_config import LanguageModelConfig\n", + "from graphrag.language_model.manager import ModelManager\n", + "from graphrag.tokenizer.get_tokenizer import get_tokenizer\n", + "\n", + "api_key = os.environ[\"GRAPHRAG_API_KEY\"]\n", + "\n", + "chat_config = LanguageModelConfig(\n", + " api_key=api_key,\n", + " type=ModelType.Chat,\n", + " model_provider=\"openai\",\n", + " model=\"gpt-4.1\",\n", + " max_retries=20,\n", + ")\n", + "chat_model = ModelManager().get_or_create_chat_model(\n", + " name=\"local_search\",\n", + " model_type=ModelType.Chat,\n", + " config=chat_config,\n", + ")\n", + "\n", + "embedding_config = LanguageModelConfig(\n", + " api_key=api_key,\n", + " type=ModelType.Embedding,\n", + " model_provider=\"openai\",\n", + " model=\"text-embedding-3-small\",\n", + " max_retries=20,\n", + ")\n", + "\n", + "text_embedder = ModelManager().get_or_create_embedding_model(\n", + " name=\"local_search_embedding\",\n", + " model_type=ModelType.Embedding,\n", + " config=embedding_config,\n", + ")\n", + "\n", + "tokenizer = get_tokenizer(chat_config)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create local search context builder" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "context_builder = LocalSearchMixedContext(\n", + " community_reports=reports,\n", + " text_units=text_units,\n", + " entities=entities,\n", + " relationships=relationships,\n", + " # if you did not run covariates during indexing, set this to None\n", + " covariates=covariates,\n", + " entity_text_embeddings=description_embedding_store,\n", + " embedding_vectorstore_key=EntityVectorStoreKey.ID, # if the vectorstore uses entity title as ids, set this to EntityVectorStoreKey.TITLE\n", + " text_embedder=text_embedder,\n", + " tokenizer=tokenizer,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Create local search engine" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# text_unit_prop: proportion of context window dedicated to related text units\n", + "# community_prop: proportion of context window dedicated to community reports.\n", + "# The remaining proportion is dedicated to entities and relationships. Sum of text_unit_prop and community_prop should be <= 1\n", + "# conversation_history_max_turns: maximum number of turns to include in the conversation history.\n", + "# conversation_history_user_turns_only: if True, only include user queries in the conversation history.\n", + "# top_k_mapped_entities: number of related entities to retrieve from the entity description embedding store.\n", + "# top_k_relationships: control the number of out-of-network relationships to pull into the context window.\n", + "# include_entity_rank: if True, include the entity rank in the entity table in the context window. Default entity rank = node degree.\n", + "# include_relationship_weight: if True, include the relationship weight in the context window.\n", + "# include_community_rank: if True, include the community rank in the context window.\n", + "# return_candidate_context: if True, return a set of dataframes containing all candidate entity/relationship/covariate records that\n", + "# could be relevant. Note that not all of these records will be included in the context window. The \"in_context\" column in these\n", + "# dataframes indicates whether the record is included in the context window.\n", + "# max_tokens: maximum number of tokens to use for the context window.\n", + "\n", + "\n", + "local_context_params = {\n", + " \"text_unit_prop\": 0.5,\n", + " \"community_prop\": 0.1,\n", + " \"conversation_history_max_turns\": 5,\n", + " \"conversation_history_user_turns_only\": True,\n", + " \"top_k_mapped_entities\": 10,\n", + " \"top_k_relationships\": 10,\n", + " \"include_entity_rank\": True,\n", + " \"include_relationship_weight\": True,\n", + " \"include_community_rank\": False,\n", + " \"return_candidate_context\": False,\n", + " \"embedding_vectorstore_key\": EntityVectorStoreKey.ID, # set this to EntityVectorStoreKey.TITLE if the vectorstore uses entity title as ids\n", + " \"max_tokens\": 12_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 5000)\n", + "}\n", + "\n", + "model_params = {\n", + " \"max_tokens\": 2_000, # change this based on the token limit you have on your model (if you are using a model with 8k limit, a good setting could be 1000=1500)\n", + " \"temperature\": 0.0,\n", + "}" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "search_engine = LocalSearch(\n", + " model=chat_model,\n", + " context_builder=context_builder,\n", + " tokenizer=tokenizer,\n", + " model_params=model_params,\n", + " context_builder_params=local_context_params,\n", + " response_type=\"multiple paragraphs\", # free form text describing the response type and format, can be anything, e.g. prioritized list, single paragraph, multiple paragraphs, multiple-page report\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Run local search on sample queries" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result = await search_engine.search(\"Tell me about Agent Mercer\")\n", + "print(result.response)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "question = \"Tell me about Dr. Jordan Hayes\"\n", + "result = await search_engine.search(question)\n", + "print(result.response)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Inspecting the context data used to generate the response" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result.context_data[\"entities\"].head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result.context_data[\"relationships\"].head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "if \"reports\" in result.context_data:\n", + " result.context_data[\"reports\"].head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "result.context_data[\"sources\"].head()" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "if \"claims\" in result.context_data:\n", + " print(result.context_data[\"claims\"].head())" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Question Generation" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This function takes a list of user queries and generates the next candidate questions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "question_generator = LocalQuestionGen(\n", + " model=chat_model,\n", + " context_builder=context_builder,\n", + " tokenizer=tokenizer,\n", + " model_params=model_params,\n", + " context_builder_params=local_context_params,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "question_history = [\n", + " \"Tell me about Agent Mercer\",\n", + " \"What happens in Dulce military base?\",\n", + "]\n", + "candidate_questions = await question_generator.agenerate(\n", + " question_history=question_history, context_data=None, question_count=5\n", + ")\n", + "print(candidate_questions.response)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "graphrag", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.10" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/get_started.zh.md b/docs/get_started.zh.md new file mode 100644 index 0000000000..51707c3f38 --- /dev/null +++ b/docs/get_started.zh.md @@ -0,0 +1,134 @@ +# 快速开始 + +⚠️ GraphRAG 可能会消耗大量 LLM 资源！我们强烈建议在理解系统工作方式之前，先从这里的教程数据集开始，并考虑先使用快速/低成本模型进行实验，再决定是否投入大型索引任务。 + +## 要求 + +[Python 3.10-3.12](https://www.python.org/downloads/) + +以下是在从 [pypi](https://pypi.org/project/graphrag/) 安装后，在命令行中使用 GraphRAG 的一个简单端到端示例。 + +它展示了如何使用该系统为一些文本建立索引，然后使用索引后的数据来回答有关文档的问题。 + +## 安装 GraphRAG + +要开始使用，请创建一个项目空间和 python 虚拟环境来安装 `graphrag`。 + +### 创建项目空间 + +```bash +mkdir graphrag_quickstart +cd graphrag_quickstart +python -m venv .venv +``` + +### 激活 Python 虚拟环境 - Unix/MacOS + +```bash +source .venv/bin/activate +``` + +### 激活 Python 虚拟环境 - Windows + +```bash +.venv\Scripts\activate +``` + +### 安装 GraphRAG + +```bash +python -m pip install graphrag +``` + +### 初始化 GraphRAG + +要初始化工作区，首先运行 `graphrag init` 命令。 + +```sh +graphrag init +``` + +出现提示时，请在配置中指定你希望使用的默认聊天模型和嵌入模型。 + +这将在当前目录中创建两个文件 `.env` 和 `settings.yaml`，以及一个目录 `input`。 + +- `input` 使用 `graphrag` 处理的文本文件位置。 +- `.env` 包含运行 GraphRAG 流水线所需的环境变量。如果你查看该文件，会看到定义了一个环境变量， + `GRAPHRAG_API_KEY=`。请将 `` 替换为你自己的 OpenAI 或 Azure API 密钥。 +- `settings.yaml` 包含流水线的设置。你可以修改此文件以更改流水线的设置。 + +### 下载示例文本 + +从可信来源获取 Charles Dickens 的《A Christmas Carol》副本： + +```sh +curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt +``` + +## 设置工作区变量 + +### 使用 OpenAI + +如果以 OpenAI 模式运行，你只需要将 `.env` 文件中的 `GRAPHRAG_API_KEY` 值更新为你的 OpenAI API 密钥。 + +### 使用 Azure OpenAI + +除了设置 API 密钥之外，Azure OpenAI 用户还应在 settings.yaml 文件中设置以下变量。要找到相应部分，只需搜索 `models:` 根配置；你应该会看到两个部分，一个用于默认聊天端点，另一个用于默认嵌入端点。以下是添加到聊天模型配置中的示例： + +```yaml +type: chat +model_provider: azure +model: gpt-4.1 +azure_deployment_name: +api_base: https://.openai.azure.com +api_version: 2024-02-15-preview # 你可以为其他版本自定义此项 +``` + +#### 在 Azure 上使用托管身份验证 + +要使用托管身份验证，请编辑模型配置中的 auth_method 并删除 api_key 行： + +```yaml +auth_method: azure_managed_identity # 默认 auth_method 是 is api_key +``` + +你还需要使用 [az login](https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli) 登录，并选择与你的端点对应的订阅。 + +## 建立索引 + +现在我们已经准备好建立索引了！ + +```sh +graphrag index +``` + +![从 CLI 执行的流水线](img/pipeline-running.png) + +此过程通常需要几分钟才能运行完成。流水线完成后，你应该会看到一个名为 `./output` 的新文件夹，其中包含一系列 parquet 文件。 + +# 查询 + +现在让我们使用这个数据集来提一些问题。 + +下面是一个使用全局搜索提出高层次问题的示例： + +```sh +graphrag query "What are the top themes in this story?" +``` + +下面是一个使用本地搜索针对特定角色提出更具体问题的示例： + +```sh +graphrag query \ +"Who is Scrooge and what are his main relationships?" \ +--method local +``` + +有关在索引器执行完成后，如何利用我们的本地搜索和全局搜索机制从数据中提取有意义见解的详细信息，请参阅 [Query Engine](query/overview.md) 文档。 + +# 深入了解 + +- 有关配置 GraphRAG 的更多详细信息，请参阅[配置文档](config/overview.md)。 +- 要了解有关初始化的更多信息，请参阅[初始化文档](config/init.md)。 +- 有关使用 CLI 的更多详细信息，请参阅 [CLI 文档](cli.md)。 +- 请查看我们的[可视化指南](visualization_guide.md)，以获得更具交互性的调试和探索知识图谱体验。 \ No newline at end of file diff --git a/docs/index.zh.md b/docs/index.zh.md new file mode 100644 index 0000000000..141348e566 --- /dev/null +++ b/docs/index.zh.md @@ -0,0 +1,61 @@ +# 欢迎使用 GraphRAG + +👉 [Microsoft Research 博客文章](https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/)
+👉 [GraphRAG Arxiv](https://arxiv.org/pdf/2404.16130) + +

+图 1：使用 GPT-4 Turbo 基于私有数据集构建的由 LLM 生成的知识图谱。 +

+

+图 1：使用 GPT-4 Turbo 构建的由 LLM 生成的知识图谱。 +

+ +GraphRAG 是一种结构化、分层式的 Retrieval Augmented Generation (RAG) 方法，与使用纯文本片段的朴素语义搜索方法不同。GraphRAG 流程包括从原始文本中提取知识图谱、构建社区层级、为这些社区生成摘要，然后在执行基于 RAG 的任务时利用这些结构。 + +要进一步了解 GraphRAG 及其如何用于增强你的语言模型对私有数据的推理能力，请访问 [Microsoft Research 博客文章](https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/)。 + +## 开始使用 GraphRAG 🚀 + +要开始使用 GraphRAG，请查看 [_Get Started_](get_started.md) 指南。 +若想更深入了解主要子系统，请访问 [Indexer](index/overview.md) 和 [Query](query/overview.md) 包的文档页面。 + +## GraphRAG 与基线 RAG 对比 🔍 + +Retrieval-Augmented Generation (RAG) 是一种使用现实世界信息改进 LLM 输出的技术。这项技术是大多数基于 LLM 工具的重要组成部分，而绝大多数 RAG 方法使用向量相似度作为搜索技术，我们将其称为 _Baseline RAG_。GraphRAG 使用知识图谱，在针对复杂信息进行推理时，显著提升问答性能。RAG 技术已显示出帮助 LLM 对 _私有数据集_ 进行推理的潜力——这些数据是 LLM 未经过训练且此前从未见过的数据，例如企业的专有研究、业务文档或通信内容。_Baseline RAG_ 正是为帮助解决这一问题而创建的，但我们观察到在某些情况下，基线 RAG 的表现非常差。例如： + +- Baseline RAG 很难将线索串联起来。当回答一个问题需要通过共享属性遍历彼此分散的信息片段，从而提供新的综合洞见时，就会出现这种情况。 +- 当被要求对大型数据集合，甚至单个大型文档中的已总结语义概念进行整体理解时，Baseline RAG 表现不佳。 + +为了解决这个问题，技术社区正在努力开发扩展和增强 RAG 的方法。Microsoft Research 的新方法 GraphRAG 会基于输入语料创建知识图谱。该图谱连同社区摘要和图机器学习输出，会在查询时用于增强提示。GraphRAG 在回答上述两类问题时表现出显著提升，展现出优于此前应用于私有数据集的其他方法的智能性或掌握程度。 + +## GraphRAG 流程 🤖 + +GraphRAG 基于我们先前使用图机器学习开展的 [研究](https://www.microsoft.com/en-us/worklab/patterns-hidden-inside-the-org-chart) 和 [工具](https://github.com/graspologic-org/graspologic)。GraphRAG 流程的基本步骤如下： + +### 索引 + +- 将输入语料切分为一系列 TextUnits，它们作为后续流程中可分析的单元，并在输出中提供细粒度引用。 +- 从 TextUnits 中提取所有实体、关系和关键主张。 +- 使用 [Leiden technique](https://arxiv.org/pdf/1810.08473.pdf) 对图进行层次聚类。若想直观查看，请参见上面的图 1。每个圆圈都是一个实体（例如人物、地点或组织），其大小表示实体的度，颜色表示其所属社区。 +- 自底向上生成每个社区及其组成部分的摘要。这有助于对数据集进行整体理解。 + +### 查询 + +在查询时，这些结构会用于为 LLM 上下文窗口提供回答问题所需的材料。主要查询模式包括： + +- 使用社区摘要对语料进行整体性问题推理的 [_Global Search_](query/global_search.md)。 +- 通过扩展到特定实体的邻居及相关概念来进行推理的 [_Local Search_](query/local_search.md)。 +- 通过扩展到特定实体的邻居及相关概念，并加入社区信息这一额外上下文来进行推理的 [_DRIFT Search_](query/drift_search.md)。 +- _Basic Search_，适用于你的查询最好由基线 RAG 回答的情况（标准 top _k_ 向量搜索）。 + +### 提示词调优 + +直接开箱即用地将 _GraphRAG_ 应用于你的数据，可能无法获得最佳结果。 +我们强烈建议你按照文档中的 [Prompt Tuning Guide](prompt_tuning/overview.md) 对提示词进行微调。 + + +## 版本控制 + +有关我们项目版本控制方法的说明，请参阅 [breaking changes](https://github.com/microsoft/graphrag/blob/main/breaking-changes.md) 文档。 + +*请务必在每次次版本号升级之间运行 `graphrag init --root [path] --force`，以确保你拥有最新的配置格式。如果你希望避免重新索引先前的数据集，请在主版本号升级之间运行提供的迁移 notebook。请注意，这将覆盖你的配置和提示词，因此如有必要请提前备份。* \ No newline at end of file diff --git a/docs/index/architecture.zh.md b/docs/index/architecture.zh.md new file mode 100644 index 0000000000..866742cc9b --- /dev/null +++ b/docs/index/architecture.zh.md @@ -0,0 +1,53 @@ +# 索引架构 + +## 关键概念 + +### 知识模型 + +为了支持 GraphRAG 系统，索引引擎的输出（在默认配置模式下）与一个我们称为 _GraphRAG Knowledge Model_ 的知识模型保持一致。 +该模型旨在作为底层数据存储技术之上的一种抽象，并为 GraphRAG 系统提供一个可交互的通用接口。 + +### 工作流 + +下面是 GraphRAG 的核心索引流水线。各个工作流的详细说明见 [dataflow](./default_dataflow.md) 页面。 + +```mermaid +--- +title: Basic GraphRAG +--- +stateDiagram-v2 + [*] --> LoadDocuments + LoadDocuments --> ChunkDocuments + ChunkDocuments --> ExtractGraph + ChunkDocuments --> ExtractClaims + ChunkDocuments --> EmbedChunks + ExtractGraph --> DetectCommunities + ExtractGraph --> EmbedEntities + DetectCommunities --> GenerateReports + GenerateReports --> EmbedReports +``` + +### LLM 缓存 + +GraphRAG 库在设计时就考虑了 LLM 交互，而在使用 LLM API 时，一个常见的挫折是由于网络延迟、限流等导致的各种错误。 +由于存在这些潜在的错误情况，我们在 LLM 交互外围增加了一层缓存。 +当使用相同的输入集（提示词和调优参数）发起补全请求时，如果存在缓存结果，我们就返回该结果。 +这使我们的索引器能够更好地抵御网络问题、以幂等方式运行，并为最终用户提供更高效的体验。 + +### 提供程序与工厂 + +GraphRAG 中的多个子系统使用工厂模式来注册和检索提供程序实现。这允许进行深度定制，以支持你自己的模型、存储等实现，即使这些实现尚未内置到核心库中。 + +以下子系统使用了工厂模式，允许你注册自己的实现： + +- [language model](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-llm/graphrag_llm/completion/completion_factory.py) - 实现你自己的 `chat` 和 `embed` 方法，以使用你所选择的模型提供程序，而不局限于内置的 LiteLLM 包装器 +- [input reader](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-input/graphrag_input/input_reader.py) - 实现你自己的输入文档读取器，以支持除 text、CSV 和 JSON 之外的文件类型 +- [cache](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-cache/graphrag_cache/cache_factory.py) - 除了我们提供的 file、blob 和 CosmosDB 之外，创建你自己的缓存存储位置 +- [logger](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/logger/factory.py) - 除了内置的 file 和 blob 存储之外，创建你自己的日志写入位置 +- [storage](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-storage/graphrag_storage/tables/table_provider_factory.py) - 创建你自己的存储提供程序（数据库等），而不局限于内置的 file、blob 和 CosmosDB +- [vector store](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-vectors/graphrag_vectors/vector_store_factory.py) - 实现你自己的向量存储，而不是使用内置的 lancedb、Azure AI Search 和 CosmosDB +- [pipeline + workflows](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/index/workflows/factory.py) - 使用自定义的 `run_workflow` 函数实现你自己的工作流步骤，或者注册整个流水线（具名工作流列表） + +这些子系统对应的链接都指向工厂的源代码，其中包含默认内置实现的注册。此外，我们还对 [language models](../config/models.md) 进行了详细讨论，其中包含一个自定义提供程序的示例，以及一个演示自定义向量存储的 [sample notebook](../examples_notebooks/custom_vector_store.ipynb)。 + +所有这些工厂都允许你使用任意字符串名称来注册一个实现，甚至可以直接覆盖内置实现。 \ No newline at end of file diff --git a/docs/index/byog.zh.md b/docs/index/byog.zh.md new file mode 100644 index 0000000000..101caa60d9 --- /dev/null +++ b/docs/index/byog.zh.md @@ -0,0 +1,68 @@ +# 自带图谱 + +一些用户曾询问，他们是否可以自带现有图谱，并使用 GraphRAG 对其进行摘要以供查询。实现这一点有很多种可能的方法，但这里我们将描述一种简单的方法，它能够相当容易地与现有的 GraphRAG 工作流对齐。 + +为了覆盖 GraphRAG 查询的基本用例，你应该拥有两个或三个从你的数据派生出的表： + +- entities.parquet - 这是在数据集中发现的实体列表，即图的节点。 +- relationships.parquet - 这是在数据集中发现的关系列表，即图的边。 +- text_units.parquet - 这是提取图谱时所依据的源文本块。根据你打算使用的查询方法，这一项是可选的（后文会说明）。 + +这里描述的方法是运行一个自定义的 GraphRAG 工作流管道，该管道假定文本分块、实体提取和关系提取已经完成。 + +## 表 + +### 实体 + +请参阅完整的实体[表结构](./outputs.md#entities)。出于图摘要的目的，你只需要 id、title、description 以及 text_unit_ids 列表。 + +### 关系 + +请参阅完整的关系[表结构](./outputs.md#relationships)。出于图摘要的目的，你只需要 id、source、target、description、weight 以及 text_unit_ids 列表。 + +> 注意：`weight` 字段很重要，因为它用于正确计算 Leiden 社区！ + +## 工作流配置 + +GraphRAG 支持仅指定你所需的特定工作流步骤。对于基本的图摘要和查询，你需要在 settings.yaml 中使用以下配置： + +```yaml +workflows: [create_communities, create_community_reports] +``` + +这将仅运行 GraphRAG [全局搜索](../query/global_search.md) 所需的最小工作流。 + +## 可选附加配置 + +如果你想运行 [本地](../query/local_search.md)、[DRIFT](../query/drift_search.md) 或 [基础](../query/overview.md#basic-search) 搜索，则需要包含 text_units 和一些嵌入。 + +### 文本单元 + +请参阅完整的 text_units [表结构](./outputs.md#text_units)。文本单元是文档的分块，其大小经过控制，以确保能够适配你的模型的上下文窗口。某些搜索方法会使用它们，因此如果你有这些数据，可能希望将其包含进来。 + +### 扩展配置 + +要执行上述其他搜索类型，你需要对部分内容进行嵌入。只需添加 embeddings 工作流： + +```yaml +workflows: [create_communities, create_community_reports, generate_text_embeddings] +``` + +### FastGraphRAG + +[FastGraphRAG](./methods.md#fastgraphrag) 在社区报告中使用 text_units，而不是实体和关系描述。如果你的图谱来源方式使其不包含描述，这可能是一个有用的替代方案。在这种情况下，你需要更新 workflows 列表，以包含社区报告工作流的文本变体： + +```yaml +workflows: [create_communities, create_community_reports_text, generate_text_embeddings] +``` + +此方法要求你的 entities 和 relationships 表具有指向 text_unit_ids 列表的有效链接。另请注意，只有当你执行除全局搜索之外的搜索时，才仍然需要 `generate_text_embeddings`。 + + +## 设置 + +综合起来： + +- `output`：创建一个输出文件夹，并将你的 entities 和 relationships（以及可选的 text_units）parquet 文件放入其中。 +- 按照上述说明更新你的配置，只运行你所需的那部分工作流。 +- 运行 `graphrag index --root ` \ No newline at end of file diff --git a/docs/index/default_dataflow.zh.md b/docs/index/default_dataflow.zh.md new file mode 100644 index 0000000000..4215bd207e --- /dev/null +++ b/docs/index/default_dataflow.zh.md @@ -0,0 +1,182 @@ +# 数据索引流程 + +## GraphRAG 知识模型 + +知识模型是对符合我们数据模型定义的数据输出的一种规范。你可以在 GraphRAG 仓库中的 `python/graphrag/graphrag/model` 文件夹内找到这些定义。提供了以下实体类型。这里的字段表示默认会进行文本嵌入的字段。 + +- `Document` - 系统中的输入文档。这些可以表示 CSV 中的单独行，或单独的 .txt 文件。 +- `TextUnit` - 用于分析的一段文本。这些文本块的大小、重叠情况，以及它们是否遵循任何数据边界，都可以在下方进行配置。 +- `Entity` - 从 TextUnit 中提取的实体。这些可以表示人物、地点、事件，或你提供的其他某种实体模型。 +- `Relationship` - 两个实体之间的关系。 +- `Covariate` - 提取出的声明信息，包含关于实体的陈述，这些陈述可能具有时间约束。 +- `Community` - 在实体和关系构成的图建立之后，我们会对其执行分层社区检测，以创建聚类结构。 +- `Community Report` - 每个社区的内容会被总结为生成的报告，便于人工阅读和下游搜索。 + +## 默认配置工作流 + +让我们来看一下默认配置工作流如何将文本文档转换为 _GraphRAG 知识模型_。本页对该过程中的主要步骤进行了总体概述。要完整配置此工作流，请参阅 [configuration](../config/overview.md) 文档。 + +```mermaid +--- +title: Dataflow Overview +--- +flowchart TB + subgraph phase1[Phase 1: Compose TextUnits] + documents[Documents] --> chunk[Chunk] + chunk --> textUnits[Text Units] + end + subgraph phase2[Phase 2: Document Processing] + documents --> link_to_text_units[Link to TextUnits] + textUnits --> link_to_text_units + link_to_text_units --> document_outputs[Documents Table] + end + subgraph phase3[Phase 3 Graph Extraction] + textUnits --> graph_extract[Entity & Relationship Extraction] + graph_extract --> graph_summarize[Entity & Relationship Summarization] + graph_summarize --> claim_extraction[Claim Extraction] + claim_extraction --> graph_outputs[Graph Tables] + end + subgraph phase4[Phase 4: Graph Augmentation] + graph_outputs --> community_detect[Community Detection] + community_detect --> community_outputs[Communities Table] + end + subgraph phase5[Phase 5: Community Summarization] + community_outputs --> summarized_communities[Community Summarization] + summarized_communities --> community_report_outputs[Community Reports Table] + end + subgraph phase6[Phase 6: Text Embeddings] + textUnits --> text_embed[Text Embedding] + graph_outputs --> description_embed[Description Embedding] + community_report_outputs --> content_embed[Content Embedding] + end +``` + +## 第 1 阶段：构建 TextUnits + +默认配置工作流的第一阶段是将输入文档转换为 _TextUnits_。_TextUnit_ 是一段用于图提取技术的文本。它们还会被提取出的知识项作为源引用使用，从而支持通过概念回溯到原始源文本的线索和溯源能力。 + +块大小（以 token 计）可由用户配置。默认设置为 1200 个 token。更大的文本块会导致输出保真度更低、引用文本意义更弱；但使用更大的文本块可以显著加快处理速度。 + +```mermaid +--- +title: Documents into Text Chunks +--- +flowchart LR + doc1[Document 1] --> tu1[TextUnit 1] + doc1 --> tu2[TextUnit 2] + doc2[Document 2] --> tu3[TextUnit 3] + doc2 --> tu4[TextUnit 4] + +``` + +## 第 2 阶段：文档处理 + +在工作流的这一阶段，我们为知识模型创建 _Documents_ 表。最终文档不会在 GraphRAG 中被直接使用，但这一步会将它们与其组成的文本单元关联起来，以便在你自己的应用程序中进行溯源。 + +```mermaid +--- +title: Document Processing +--- +flowchart LR + aug[Augment] --> dp[Link to TextUnits] --> dg[Documents Table] +``` + +### 链接到 TextUnits + +在这一步中，我们将每个文档链接到第一阶段中创建的文本单元。这使我们能够了解哪些文档与哪些文本单元相关，反之亦然。 + +### Documents 表 + +此时，我们可以将 **Documents** 表导出到知识模型中。 + +## 第 3 阶段：图提取 + +在这一阶段，我们分析每个文本单元并提取图的基本元素：_Entities_、_Relationships_ 和 _Claims_。 +Entities 和 Relationships 会在我们的 _extract_graph_ 工作流中一次性提取，而 claims 会在我们的 _extract_claims_ 工作流中提取。随后结果会被合并并传递到流水线的后续阶段。 + +```mermaid +--- +title: Graph Extraction +--- +flowchart LR + tu[TextUnit] --> ge[Graph Extraction] --> gs[Graph Summarization] + tu --> ce[Claim Extraction] +``` + +> 注意：如果你使用的是 [FastGraphRAG](https://microsoft.github.io/graphrag/index/methods/#fastgraphrag) 选项，实体和关系提取将使用 NLP 执行，以节省 LLM 资源，而声明提取将始终被跳过。 + +### 实体与关系提取 + +在图提取的第一步中，我们使用 LLM 处理每个文本单元，从原始文本中提取实体和关系。这一步的输出是每个 TextUnit 一个子图，其中包含一个 **entities** 列表，每个实体具有 _title_、_type_ 和 _description_，以及一个 **relationships** 列表，每个关系具有 _source_、_target_ 和 _description_。 + +随后这些子图会被合并——任何具有相同 _title_ 和 _type_ 的实体都会通过创建其描述数组的方式合并。类似地，任何具有相同 _source_ 和 _target_ 的关系也会通过创建其描述数组的方式合并。 + +### 实体与关系总结 + +现在我们已经有了一个实体和关系的图，并且每个实体和关系都带有描述列表，我们就可以将这些列表总结为每个实体和关系的一条单独描述。做法是请求 LLM 生成一个简短摘要，涵盖每条描述中的所有不同信息。这样，我们的所有实体和关系都将拥有一条简洁的单一描述。 + +### 声明提取（可选） + +最后，作为一个独立工作流，我们从源 TextUnits 中提取声明。这些声明表示具有已评估状态和时间边界的正向事实陈述。它们会作为名为 **Covariates** 的主要产物导出。 + +注意：声明提取是 _可选_ 的，默认关闭。这是因为声明提取通常需要进行提示调优才会有用。 + +## 第 4 阶段：图增强 + +现在我们已经有了可用的实体与关系图，我们希望理解它们的社区结构。这为我们提供了理解图组织方式的明确途径。 + +```mermaid +--- +title: Graph Augmentation +--- +flowchart LR + cd[Leiden Hierarchical Community Detection] --> ag[Graph Tables] +``` + +### 社区检测 + +在这一步中，我们使用分层 Leiden 算法生成实体社区的层次结构。该方法会对图递归地应用社区聚类，直到达到社区大小阈值。这将使我们能够理解图的社区结构，并提供一种以不同粒度导航和总结图的方式。 + +### 图表 + +一旦图增强步骤完成，最终的 **Entities**、**Relationships** 和 **Communities** 表就会被导出。 + +## 第 5 阶段：社区总结 + +```mermaid +--- +title: Community Summarization +--- +flowchart LR + sc[Generate Community Reports] --> ss[Summarize Community Reports] --> co[Community Reports Table] +``` + +此时，我们已经拥有一个可用的实体与关系图，以及实体的社区层次结构。 + +现在我们希望基于社区数据，为每个社区生成报告。这使我们能够在图的多个粒度层级上获得对图的高层理解。例如，如果社区 A 是顶层社区，我们将获得关于整个图的报告。如果该社区处于较低层级，我们将获得关于局部簇的报告。 + +### 生成社区报告 + +在这一步中，我们使用 LLM 为每个社区生成摘要。这将使我们能够理解每个社区中包含的独特信息，并从高层或低层视角对图提供范围限定的理解。这些报告包含执行概览，并引用社区子结构中的关键实体、关系和声明。 + +### 总结社区报告 + +在这一步中，每个 _community report_ 随后都会通过 LLM 进一步总结，以便简写使用。 + +### Community Reports 表 + +此时，会执行一些记录整理工作，并导出 **Community Reports** 表。 + +## 第 6 阶段：文本嵌入 + +对于所有需要下游向量搜索的产物，我们在最后一步生成文本嵌入。这些嵌入会被直接写入已配置的向量存储。默认情况下，我们会嵌入实体描述、文本单元文本以及社区报告文本。 + +```mermaid +--- +title: Text Embedding Workflows +--- +flowchart LR + textUnits[Text Units] --> text_embed[Text Embedding] + graph_outputs[Graph Tables] --> description_embed[Description Embedding] + community_report_outputs[Community Reports] --> content_embed[Content Embedding] +``` \ No newline at end of file diff --git a/docs/index/inputs.zh.md b/docs/index/inputs.zh.md new file mode 100644 index 0000000000..9befdfbcd2 --- /dev/null +++ b/docs/index/inputs.zh.md @@ -0,0 +1,224 @@ +# 输入 + +GraphRAG 支持多种输入格式，以简化数据摄取。这里将讨论输入文件和文本分块可用的机制与功能。 + +## 输入加载与架构 + +所有输入格式都会在 GraphRAG 中加载，并作为 `documents` DataFrame 传递给索引流水线。该 DataFrame 为每个文档包含一行，并使用共享的列架构： + +| name | type | description | +| ------------- | ---- | ----------- | +| id | str | 文档的 ID。它使用文本内容的哈希生成，以确保在多次运行之间保持稳定。 | +| text | str | 文档的完整文本。 | +| title | str | 文档名称。某些格式允许对此进行配置。 | +| creation_date | str | 文档的创建日期，以 ISO8601 字符串表示。这是从源文件系统中提取的。 | +| metadata | dict | 可选的附加文档元数据。更多细节见下文。 | + +另请参阅 [outputs](outputs.md) 文档，了解流水线完成后保存到 parquet 的最终 documents 表架构。 + +## 自带 DataFrame + +GraphRAG 的 [索引 API 方法](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/api/index.py) 允许你传入自己的 pandas DataFrame，并绕过下一节中描述的所有输入加载/解析过程。如果你的内容采用我们开箱即用不支持的格式或存储位置，这会很方便。_你必须确保输入的 DataFrame 符合上述架构。_ 后文描述的所有分块行为都将完全相同地进行。 + +## 自定义文件处理 + +我们使用可注入的 InputReader 提供程序类。这意味着你可以在一个继承 InputReader 的类中实现任何你想要的输入文件处理逻辑，并将其注册到 InputReaderFactory。有关我们标准提供程序模式的更多信息，请参阅 [architecture page](https://microsoft.github.io/graphrag/index/architecture/)。 + +## 格式 + +我们开箱即用支持三种文件格式。这覆盖了我们遇到的绝大多数用例。如果你使用的是不同格式，我们建议你要么实现自己的 InputReader，要么编写脚本转换为以下格式之一，因为它们被广泛使用，并受到许多工具和库的支持。 + +### 纯文本 + +纯文本文件（通常以 .txt 文件扩展名结尾）。对于纯文本文件，我们将整个文件内容导入为 `text` 字段，而 `title` 始终为文件名。 + +### 逗号分隔 + +CSV 文件（通常以 .csv 扩展名结尾）。这些文件使用 pandas 的默认选项通过 [`read_csv` method](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html) 加载。CSV 文件中的每一行都被视为单个文档。如果你的输入文件夹中有多个 CSV 文件，它们将被串联成一个结果 `documents` DataFrame。 + +对于 CSV 格式，如果你的数据包含你希望使用的结构化内容，可以配置 `text_column` 和 `title_column`。如果你没有在 settings.yaml 的 `input` 块中配置这些项，那么标题将如上面架构所述为文件名。如果未特别配置，则假定文件中的 `text_column` 为 "text"。如果存在 "id" 列，我们也会查找并使用它；否则将按上述方式生成 ID。 + +### JSON + +JSON 文件（通常以 .json 扩展名结尾）包含[结构化对象](https://www.json.org/)。这些文件使用 python 的 [`json.loads` method](https://docs.python.org/3/library/json.html) 加载，因此你的文件必须严格符合规范。JSON 文件可以在文件中包含单个对象，*或者* 文件根节点可以包含对象数组。我们会检查并处理这两种情况。与 CSV 一样，多个文件将被串联为最终表格，并且 `text_column` 与 `title_column` 配置选项会应用到每个已加载对象的属性上。请注意，一些库生成的专用 jsonl 格式（每行一个完整 JSON 对象，而不是放在数组中）目前尚不支持。 + +## 元数据 + +对于结构化文件格式（CSV 和 JSON），你可以配置任意数量的列，将其添加到 DataFrame 中持久化的 `metadata` 字段中。这是通过提供要收集的列名列表来配置的。如果配置了此项，输出的 `metadata` 列将包含一个 dict，其中每一列对应一个键，其值为该文档该列的值。这些元数据随后可以选择性地在 GraphRAG 流水线中使用。 + +### 示例 + +software.csv + +```csv +text,title,tag +My first program,Hello World,tutorial +An early space shooter game,Space Invaders,arcade +``` + +settings.yaml + +```yaml +input: + metadata: [title,tag] +``` + +Documents DataFrame + +| id | title | text | creation_date | metadata | +| --------------------- | -------------- | --------------------------- | ----------------------------- | ---------------------------------------------- | +| (generated from text) | Hello World | My first program | (create date of software.csv) | { "title": "Hello World", "tag": "tutorial" } | +| (generated from text) | Space Invaders | An early space shooter game | (create date of software.csv) | { "title": "Space Invaders", "tag": "arcade" } | + +## 分块与元数据 + +如 [default dataflow](default_dataflow.md#phase-1-compose-textunits) 页面所述，文档会被 *chunked* 成更小的“文本单元”以便处理。这样做是因为文档内容大小通常会超出给定语言模型可用的上下文窗口。你可以调整少量与此分块相关的设置，其中最重要的是 `chunk_size` 和 `overlap`。我们还支持一种元数据处理方案，它可以改善某些用例的索引结果。下面将详细说明此功能。 + +设想如下场景：你正在为一组新闻文章建立索引。每篇文章的文本都以标题和作者开头，然后是正文内容。当文档被分块时，它们会根据你配置的块大小均匀切分。换句话说，前 *n* 个 token 会被读入一个文本单元，然后是下一个 *n* 个，直到内容结束。这意味着文档开头的前置信息（例如本例中的标题和作者）*不会被复制到每个块中*。它只存在于第一个块中。当我们之后检索这些块进行摘要时，它们因此可能缺少关于源文档的共享信息，而这些信息本应始终提供给模型。为了解决这个问题，我们提供了将重复内容复制到每个文本单元中的配置选项。 + +### 输入配置 + +如上所述，导入文档时，你可以指定一个 `metadata` 列表，将其包含在每一行中。必须配置此项，每块复制功能才能工作。 + +### 分块配置 + +接下来，`chunks` 块需要指示分块器在创建文本单元时如何处理这些元数据。默认情况下，它会被忽略。我们提供以下设置来包含它： + +- `prepend_metadata`。这会指示导入器将每一行 `metadata` 列的内容复制到每个文本块的开头。这些元数据会以新行上的 key: value 对形式复制。 + +### 示例 + +下面给出几个示例，以帮助说明对于每种文件格式，分块配置和元数据前置是如何工作的。请注意，为了说明方便，我们这里将词数作为“tokens”，但语言模型的 token [并不等同于单词](https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them)。 + +#### 文本文件 + +本示例使用两个独立的新闻文章文本文件。 + +-- + +**File:** US to lift most federal COVID-19 vaccine mandates.txt + +**Content:** + +WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. "While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down," White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday. + +-- + +**File:** NY lawmakers begin debating budget 1 month after due date.txt + +**Content:** + +ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to be wrapped up Tuesday for a budget she said contains "significant wins" for New Yorkers. "I would have liked to have done this sooner. I think we would all agree to that," Cousins told reporters before voting began. "This has been a very policy-laden budget and a lot of the policies had to parsed through." Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the "least restrictive" means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate. + +-- + +settings.yaml + +```yaml +input: + type: text + metadata: [title] + +chunks: + size: 100 + overlap: 0 + prepend_metadata: true +``` + +Documents DataFrame + +| id | title | text | creation_date | metadata | +| --------------------- | ------------------------------------------------------------- | --------------------------- | --------------------------------- | ---------------------------------------------------------------------------- | +| (generated from text) | US to lift most federal COVID-19 vaccine mandates.txt | (full content of text file) | (create date of article txt file) | { "title": "US to lift most federal COVID-19 vaccine mandates.txt" } | +| (generated from text) | NY lawmakers begin debating budget 1 month after due date.txt | (full content of text file) | (create date of article txt file) | { "title": "NY lawmakers begin debating budget 1 month after due date.txt" } | + +Raw Text Chunks + +| content | length | +| ------- | ------: | +| title: US to lift most federal COVID-19 vaccine mandates.txt
WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as | 109 | +| title: US to lift most federal COVID-19 vaccine mandates.txt
the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. "While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down," White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday. | 82 | +| title: NY lawmakers begin debating budget 1 month after due date.txt
ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to | 111 | +| title: NY lawmakers begin debating budget 1 month after due date.txt
be wrapped up Tuesday for a budget she said contains "significant wins" for New Yorkers. "I would have liked to have done this sooner. I think we would all agree to that," Cousins told reporters before voting began. "This has been a very policy-laden budget and a lot of the policies had to parsed through." Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the "least restrictive" means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it | 111 | +| title: NY lawmakers begin debating budget 1 month after due date.txt
would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate. | 89 | + +在此示例中，我们可以看到这两个输入文档被解析成了五个输出文本块。每个文档的标题（文件名）都被前置，但不计入计算出的块大小。还要注意，每个文档的最后一个文本块通常会小于块大小，因为它包含的是最后一批 token。 + +#### CSV 文件 + +本示例使用单个 CSV 文件，其中两行是与上面相同的两篇文章（请注意，文本内容并未针对实际 CSV 使用进行正确转义）。 + +-- + +**File:** articles.csv + +**Content** + +headline,article + +US to lift most federal COVID-19 vaccine mandates,WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. "While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down," White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday. + +NY lawmakers begin debating budget 1 month after due date,ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to be wrapped up Tuesday for a budget she said contains "significant wins" for New Yorkers. "I would have liked to have done this sooner. I think we would all agree to that," Cousins told reporters before voting began. "This has been a very policy-laden budget and a lot of the policies had to parsed through." Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the "least restrictive" means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate. + +#### JSON 文件 + +最后这个示例对同样两篇文章中的每一篇使用一个 JSON 文件。在本示例中，我们将设置要读取的对象字段，但不会向文本块中添加元数据。 + +-- + +**File:** article1.json + +**Content** + +```json +{ + "headline": "US to lift most federal COVID-19 vaccine mandates", + "content": "WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. "While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down," White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday." +} +``` + +**File:** article2.json + +**Content** + +```json +{ + "headline": "NY lawmakers begin debating budget 1 month after due date", + "content": "ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to be wrapped up Tuesday for a budget she said contains "significant wins" for New Yorkers. "I would have liked to have done this sooner. I think we would all agree to that," Cousins told reporters before voting began. "This has been a very policy-laden budget and a lot of the policies had to parsed through." Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the "least restrictive" means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate." +} +``` + +-- + +settings.yaml + +```yaml +input: + type: json + title_column: headline + text_column: content + +chunks: + size: 100 + overlap: 10 +``` + +Documents DataFrame + +| id | title | text | creation_date | metadata | +| --------------------- | --------------------------------------------------------- | ------------------------ | ------------------------------ | -------- | +| (generated from text) | US to lift most federal COVID-19 vaccine mandates | (article column content) | (create date of article1.json) | { } | +| (generated from text) | NY lawmakers begin debating budget 1 month after due date | (article column content) | (create date of article2.json) | { } | + +Raw Text Chunks + +| content | length | +| ------- | ------: | +| WASHINGTON (AP) The Biden administration will end most of the last remaining federal COVID-19 vaccine requirements next week when the national public health emergency for the coronavirus ends, the White House said Monday. Vaccine requirements for federal workers and federal contractors, as well as foreign air travelers to the U.S., will end May 11. The government is also beginning the process of lifting shot requirements for Head Start educators, healthcare workers, and noncitizens at U.S. land borders. The requirements are among the last vestiges of some of the more coercive measures taken by the federal government to promote vaccination as | 100 | +| measures taken by the federal government to promote vaccination as the deadly virus raged, and their end marks the latest display of how President Joe Biden's administration is moving to treat COVID-19 as a routine, endemic illness. "While I believe that these vaccine mandates had a tremendous beneficial impact, we are now at a point where we think that it makes a lot of sense to pull these requirements down," White House COVID-19 coordinator Dr. Ashish Jha told The Associated Press on Monday. | 83 | +| ALBANY, N.Y. (AP) New York lawmakers began voting Monday on a $229 billion state budget due a month ago that would raise the minimum wage, crack down on illicit pot shops and ban gas stoves and furnaces in new buildings. Negotiations among Gov. Kathy Hochul and her fellow Democrats in control of the Legislature dragged on past the April 1 budget deadline, largely because of disagreements over changes to the bail law and other policy proposals included in the spending plan. Floor debates on some budget bills began Monday. State Senate Majority Leader Andrea Stewart-Cousins said she expected voting to | 100 | +| Senate Majority Leader Andrea Stewart-Cousins said she expected voting to be wrapped up Tuesday for a budget she said contains "significant wins" for New Yorkers. "I would have liked to have done this sooner. I think we would all agree to that," Cousins told reporters before voting began. "This has been a very policy-laden budget and a lot of the policies had to parsed through." Hochul was able to push through a change to the bail law that will eliminate the standard that requires judges to prescribe the "least restrictive" means to ensure defendants return to court. Hochul said judges | 100 | +| means to ensure defendants return to court. Hochul said judges needed the extra discretion. Some liberal lawmakers argued that it would undercut the sweeping bail reforms approved in 2019 and result in more people with low incomes and people of color in pretrial detention. Here are some other policy provisions that will be included in the budget, according to state officials. The minimum wage would be raised to $17 in New York City and some of its suburbs and $16 in the rest of the state by 2026. That's up from $15 in the city and $14.20 upstate. | 98 | + + +在此示例中，这两个输入文档被解析成了五个输出文本块。没有前置任何元数据，因此每个块都与配置的块大小匹配（每个文档最后一个块除外）。我们还在这些文本块中配置了一些重叠，因此最后十个 token 是共享的。 \ No newline at end of file diff --git a/docs/index/methods.zh.md b/docs/index/methods.zh.md new file mode 100644 index 0000000000..a95d11561e --- /dev/null +++ b/docs/index/methods.zh.md @@ -0,0 +1,44 @@ +# 索引方法 + +GraphRAG 是我们关于 RAG 索引方法研究的平台，这些方法旨在为语言模型生成最优的上下文窗口内容。我们有一个标准索引流水线，它使用语言模型来提取作为我们记忆模型基础的图谱。我们可能会不时引入其他索引方法。本页记录了这些选项。 + +## 标准 GraphRAG + +这是原始[博客文章](https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/)中描述的方法。标准方法在所有推理任务中都使用语言模型： + +- 实体提取：提示 LLM 从每个文本单元中提取命名实体并提供描述。 +- 关系提取：提示 LLM 描述每个文本单元中每对实体之间的关系。 +- 实体摘要：提示 LLM 将跨文本单元中发现的某个实体每次出现的描述合并为单个摘要。 +- 关系摘要：提示 LLM 将跨文本单元中发现的某个关系每次出现的描述合并为单个摘要。 +- 声明提取（可选）：提示 LLM 从每个文本单元中提取并描述声明。 +- 社区报告生成：收集每个社区的实体和关系描述（以及可选的声明），并用其提示 LLM 生成摘要报告。 + +`graphrag index --method standard`。这是默认方法，因此可以在命令行中省略 method 参数。 + +## FastGraphRAG + +FastGraphRAG 是一种用传统自然语言处理（NLP）方法替代部分语言模型推理的方法。这是我们开发的一种更快且成本更低的混合索引替代方案： + +- 实体提取：实体是使用 NLTK 和 spaCy 等 NLP 库提取的名词短语。没有描述；为此使用源文本单元。 +- 关系提取：关系被定义为实体对之间在文本单元中的共现。没有描述。 +- 实体摘要：不需要。 +- 关系摘要：不需要。 +- 声明提取：未使用。 +- 社区报告生成：收集包含每个实体名词短语的直接文本单元内容，并用其提示 LLM 生成摘要报告。 + +`graphrag index --method fast` + +FastGraphRAG 内置了一些 NLP [选项](https://microsoft.github.io/graphrag/config/yaml/#extract_graph_nlp)。默认情况下，我们使用 NLTK + 正则表达式进行名词短语提取，这种方式非常快，但主要适用于英语。我们还内置了另外两种使用 spaCy 的方法：语义解析和 CFG。默认情况下，我们为 spaCy 使用 `en_core_web_md` 模型，但请注意，你可以引用任何已安装的[受支持模型](https://spacy.io/models/)。 + +另请注意，我们通常还会将文本分块配置为生成更小的块（50-100 个 token）。这会产生更好的共现图。 + +⚠️ 关于 SpaCy 模型的说明： + +此包需要 SpaCy 模型才能正常运行。如果所需模型未安装，包会在首次使用时自动下载并安装它。 + +你也可以通过运行 `python -m spacy download ` 手动安装，例如 `python -m spacy download en_core_web_md`。 + + +## 选择方法 + +标准 GraphRAG 提供了对现实世界实体和关系的丰富描述，但比 FastGraphRAG 更昂贵。我们估计图提取约占索引成本的 75%。因此，FastGraphRAG 便宜得多，但代价是提取的图谱在 GraphRAG 之外直接使用时相关性较低，而且图谱往往噪声更大。如果高保真实体和图探索对你的用例很重要，我们建议继续使用传统 GraphRAG。如果你的用例主要面向使用全局搜索的摘要类问题，FastGraphRAG 能以更低的语言模型成本提供高质量摘要。 \ No newline at end of file diff --git a/docs/index/outputs.zh.md b/docs/index/outputs.zh.md new file mode 100644 index 0000000000..c59481e87b --- /dev/null +++ b/docs/index/outputs.zh.md @@ -0,0 +1,108 @@ +# 输出 + +默认管道会生成一系列与[概念知识模型](../index/default_dataflow.md)一致的输出表。此页面描述了详细的输出表 schema。默认情况下，我们将这些表作为磁盘上的 parquet 文件写出。 + +## 共享字段 +所有表都有两个标识符字段： + +| name | type | description | +| ----------------- | ---- | ----------- | +| id | str | 生成的 UUID，确保全局唯一性 | +| human_readable_id | int | 这是每次运行创建的递增短 ID。例如，我们在打印引用的生成摘要中使用此短 ID，以便于直观地进行交叉引用。 | + +## communities +这是由 Leiden 生成的最终社区列表。社区具有严格的层级结构，随着聚类亲和性范围缩小，会进一步细分为子社区。 + +| name | type | description | +| ------------------ | ----- | ----------- | +| community | int | 社区的 Leiden 生成聚类 ID。请注意，这些 ID 会随深度递增，因此在社区层级结构的所有层级中都是唯一的。对于此表，human_readable_id 是社区 ID 的副本，而不是普通的递增值。 | +| parent | int | 父社区 ID。| +| children | int[] | 子社区 ID 列表。| +| level | int | 社区在层级结构中的深度。 | +| title | str | 社区的易读名称。 | +| entity_ids | str[] | 属于该社区成员的实体列表。 | +| relationship_ids | str[] | 完全位于该社区内的关系列表（source 和 target 均在该社区中）。 | +| text_unit_ids | str[] | 该社区中表示的文本单元列表。 | +| period | str | 摄取日期，用于增量更新合并。ISO8601 | +| size | int | 社区大小（实体计数），用于增量更新合并。 | + +## community_reports +这是每个社区的摘要报告列表。 + +| name | type | description | +| -------------------- | ----- | ----------- | +| community | int | 此报告适用的社区短 ID。 | +| parent | int | 父社区 ID。 | +| children | int[] | 子社区 ID 列表。| +| level | int | 此报告适用的社区层级。 | +| title | str | LM 生成的报告标题。 | +| summary | str | LM 生成的报告摘要。 | +| full_content | str | LM 生成的完整报告。 | +| rank | float | LM 根据成员实体显著性得出的报告相关性排序 +| rating_explanation | str | LM 对该排序的解释。 | +| findings | dict | LM 得出的社区前 5-10 条洞察列表。包含 `summary` 和 `explanation` 值。 | +| full_content_json | json | LM 返回的完整 JSON 输出。大多数字段会被提取到列中，但此 JSON 会用于查询摘要，因此我们保留它，以便最终用户通过提示调优添加字段/内容。 | +| period | str | 摄取日期，用于增量更新合并。ISO8601 | +| size | int | 社区大小（实体计数），用于增量更新合并。 | + +## covariates +（可选）如果启用了 claim 提取，这里是提取出的协变量列表。请注意，claims 通常侧重于识别欺诈等恶意行为，因此并不适用于所有数据集。 + +| name | type | description | +| -------------- | ---- | ----------- | +| covariate_type | str | 在默认协变量中，这里始终为 "claim"。 | +| type | str | claim 类型的性质。 | +| description | str | LM 生成的行为描述。 | +| subject_id | str | 源实体的名称（即执行所声称行为的实体）。 | +| object_id | str | 目标实体的名称（即所声称行为作用的对象）。 | +| status | str | LM 对 claim 正确性的评估。[TRUE, FALSE, SUSPECTED] 之一 | +| start_date | str | LM 得出的所声称活动开始时间。ISO8601 | +| end_date | str | LM 得出的所声称活动结束时间。ISO8601 | +| source_text | str | 包含所声称行为的简短文本字符串。 | +| text_unit_id | str | 提取 claim 文本的文本单元 ID。 | + +## documents +导入后的文档内容列表。 + +| name | type | description | +| ------------- | ----- | ----------- | +| title | str | 文件名，除非在 CSV 导入期间另有配置。 | +| text | str | 文档的全文。 | +| text_unit_ids | str[] | 从文档中解析出的文本单元（chunks）列表。 | +| metadata | dict | 如果在 CSV 导入期间指定，这里是文档元数据的 dict。 | + +## entities +LM 在数据中发现的所有实体列表。 + +| name | type | description | +| ------------- | ----- | ----------- | +| title | str | 实体名称。 | +| type | str | 实体类型。默认情况下，除非进行了不同配置或使用自动调优，否则会是 "organization"、"person"、"geo" 或 "event"。 | +| description | str | 实体的文本描述。实体可能出现在许多文本单元中，因此这是 LM 对所有描述生成的摘要。 | +| text_unit_ids | str[] | 包含该实体的文本单元列表。 | +| frequency | int | 找到该实体的文本单元计数。 | +| degree | int | 图中的节点度（连接度）。 | + +## relationships +LM 在数据中发现的所有实体到实体关系列表。这也是图的 _edge list_。 + +| name | type | description | +| --------------- | ----- | ----------- | +| source | str | 源实体名称。 | +| target | str | 目标实体名称。 | +| description | str | LM 生成的关系描述。另请参见实体描述的说明。 | +| weight | float | 图中边的权重。这是对每个关系实例的 LM 生成“强度”度量求和得到的。 | +| combined_degree | int | 源节点和目标节点度数之和。 | +| text_unit_ids | str[] | 找到该关系的文本单元列表。 | + +## text_units +从输入文档解析出的所有文本块列表。 + +| name | type | description | +| ----------------- | ----- | ----------- | +| text | str | 该块的原始全文。 | +| n_tokens | int | 该块中的 token 数量。通常这应与 `chunk_size` 配置参数匹配，最后一个块通常更短，属于例外情况。 | +| document_id | str | 该块来源文档的 ID。 | +| entity_ids | str[] | 在该文本单元中找到的实体列表。 | +| relationships_ids | str[] | 在该文本单元中找到的关系列表。 | +| covariate_ids | str[] | 在该文本单元中找到的可选协变量列表。 | \ No newline at end of file diff --git a/docs/index/overview.zh.md b/docs/index/overview.zh.md new file mode 100644 index 0000000000..1eeb94821a --- /dev/null +++ b/docs/index/overview.zh.md @@ -0,0 +1,39 @@ +# GraphRAG 索引 🤖 + +GraphRAG 索引包是一个数据管道和转换套件，旨在使用 LLM 从非结构化文本中提取有意义的结构化数据。 + +索引管道是可配置的。它们由工作流、标准和自定义步骤、提示模板以及输入/输出适配器组成。我们的标准管道旨在： + +- 从原始文本中提取实体、关系和声明 +- 在实体中执行社区检测 +- 生成多个粒度级别的社区摘要和报告 +- 将文本嵌入到向量空间中 + +默认情况下，管道的输出会存储为 Parquet 表，嵌入会写入你配置的向量存储。 + +## 入门 + +### 要求 + +有关设置开发环境的详细信息，请参阅 [Get Started](../get_started.md) 中的 [requirements](../developing.md#requirements) 部分。 + +要配置 GraphRAG，请参阅 [configuration](../config/overview.md) 文档。 +有了配置文件后，你就可以使用 CLI 或 Python API 运行该管道。 + +## 用法 + +### CLI + +```bash +uv run poe index --root # default config mode +``` + +### Python API + +有关建议的直接从 Python 代码调用的方法，请参阅索引 API [python file](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/api/index.py)。 + +## 进一步阅读 + +- 要开始在 _GraphRAG_ 项目中进行开发，请参阅 [getting started](../developing.md) +- 要了解索引库的底层概念和执行模型，请参阅 [the architecture documentation](../index/architecture.md) +- 要进一步了解如何配置索引引擎，请参阅 [the configuration documentation](../config/overview.md) \ No newline at end of file diff --git a/docs/prompt_tuning/auto_prompt_tuning.zh.md b/docs/prompt_tuning/auto_prompt_tuning.zh.md new file mode 100644 index 0000000000..49a6c65b2a --- /dev/null +++ b/docs/prompt_tuning/auto_prompt_tuning.zh.md @@ -0,0 +1,91 @@ +# 自动提示词调优 ⚙️ + +GraphRAG 提供了为知识图谱生成创建领域自适应提示词的能力。此步骤是可选的，但强烈建议执行，因为它会在执行 Index Run 时产生更好的结果。 + +这些提示词通过加载输入、将其拆分为块（文本单元），然后运行一系列 LLM 调用和模板替换来生成最终提示词。我们建议使用脚本提供的默认值，但本页将提供每个参数的详细信息，以便你在需要时进一步探索和调整提示词调优算法。 + +

+Figure 1: Auto Tuning Conceptual Diagram. +

+

+图 1：自动调优概念图。 +

+ +## 前提条件 + +在运行自动调优之前，请确保你已经使用 `graphrag init` 命令初始化了工作区。这将创建必要的配置文件和默认提示词。有关初始化过程的更多信息，请参阅 [初始化文档](../config/init.md)。 + +## 用法 + +你可以通过命令行使用各种选项运行主脚本： + +```bash +graphrag prompt-tune [--root ROOT] [--domain DOMAIN] [--selection-method METHOD] [--limit LIMIT] [--language LANGUAGE] \ +[--max-tokens MAX_TOKENS] [--chunk-size CHUNK_SIZE] [--n-subset-max N_SUBSET_MAX] [--k K] \ +[--min-examples-required MIN_EXAMPLES_REQUIRED] [--discover-entity-types] [--output OUTPUT] +``` + +## 命令行选项 + +- `--root`（可选）：包含配置文件（settings.yaml）的项目目录路径。默认为当前目录。 + +- `--domain`（可选）：与你的输入数据相关的领域，例如“space science”、“microbiology”或“environmental news”。如果留空，将根据输入数据推断该领域。 + +- `--selection-method`（可选）：选择文档的方法。可选项包括 all、random、auto 或 top。默认为 random。 + +- `--limit`（可选）：在使用 random 或 top 选择时加载的文本单元数量上限。默认值为 15。 + +- `--language`（可选）：用于输入处理的语言。如果它与输入的语言不同，LLM 将进行翻译。默认值为 `""`，表示将从输入中自动检测。 + +- `--max-tokens`（可选）：用于提示词生成的最大 token 数。默认值为 2000。 + +- `--chunk-size`（可选）：从输入文档生成文本单元时使用的 token 大小。默认值为 200。 + +- `--n-subset-max`（可选）：在使用 auto 选择方法时要嵌入的文本块数量。默认值为 300。 + +- `--k`（可选）：在使用 auto 选择方法时要选择的文档数量。默认值为 15。 + +- `--min-examples-required`（可选）：实体提取提示词所需的最小示例数量。默认值为 2。 + +- `--discover-entity-types`（可选）：允许 LLM 自动发现并提取实体。我们建议在你的数据覆盖大量主题或具有很强随机性时使用此选项。 + +- `--output`（可选）：用于保存生成的提示词的文件夹。默认值为 "prompts"。 + +## 使用示例 + +```bash +python -m graphrag prompt-tune --root /path/to/project --domain "environmental news" \ +--selection-method random --limit 10 --language English --max-tokens 2048 --chunk-size 256 --min-examples-required 3 \ +--no-discover-entity-types --output /path/to/output +``` + +或者，使用最少配置（推荐）： + +```bash +python -m graphrag prompt-tune --root /path/to/project --no-discover-entity-types +``` + +## 文档选择方法 + +自动调优功能会摄取输入数据，然后将其划分为大小等于 chunk size 参数的文本单元。 +之后，它会使用以下选择方法之一挑选一个样本用于提示词生成： + +- `random`：随机选择文本单元。这是默认且推荐的选项。 +- `top`：选择前 _n_ 个文本单元。 +- `all`：使用所有文本单元进行生成。仅适用于小型数据集；通常不推荐此选项。 +- `auto`：将文本单元嵌入到低维空间中，并选择距离质心最近的 _k_ 个近邻。当你拥有大型数据集并希望选择具有代表性的样本时，这很有用。 + +## 修改配置 + +运行自动调优后，你应修改以下配置变量，以便在索引运行中使用新的提示词。注意：请确保将路径更新为生成的提示词的正确路径，在本示例中我们使用默认的 "prompts" 路径。 + +```yaml +extract_graph: + prompt: "prompts/extract_graph.txt" + +summarize_descriptions: + prompt: "prompts/summarize_descriptions.txt" + +community_reports: + prompt: "prompts/community_report.txt" +``` \ No newline at end of file diff --git a/docs/prompt_tuning/manual_prompt_tuning.zh.md b/docs/prompt_tuning/manual_prompt_tuning.zh.md new file mode 100644 index 0000000000..817711e79e --- /dev/null +++ b/docs/prompt_tuning/manual_prompt_tuning.zh.md @@ -0,0 +1,90 @@ +# 手动提示调优 ⚙️ + +GraphRAG 索引器默认会使用一组提示，这些提示旨在知识发现这一广泛场景中良好运行。 +不过，针对你的特定用例对提示进行调优是很常见的需求。 +我们提供了一种实现方式：允许你指定自定义提示文件，每个文件都会在内部使用一系列 token 替换。 + +这些提示中的每一个都可以通过编写纯文本的自定义提示文件来覆盖。我们使用 `{token_name}` 形式的 token 替换，可用 token 的说明如下所示。 + +## 索引提示 + +### 实体/关系提取 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/index/extract_graph.py) + +#### Tokens + +- **{input_text}** - 要处理的输入文本。 +- **{entity_types}** - 实体类型列表 +- **{tuple_delimiter}** - 用于分隔元组内值的分隔符。单个元组用于表示单个实体或关系。 +- **{record_delimiter}** - 用于分隔元组实例的分隔符。 +- **{completion_delimiter}** - 指示生成完成的标记。 + +### 汇总实体/关系描述 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/index/summarize_descriptions.py) + +#### Tokens + +- **{entity_name}** - 实体名称，或关系的源/目标对。 +- **{description_list}** - 实体或关系的描述列表。 + +### 声明提取 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/index/extract_claims.py) + +#### Tokens + +- **{input_text}** - 要处理的输入文本。 +- **{tuple_delimiter}** - 用于分隔元组内值的分隔符。单个元组用于表示单个实体或关系。 +- **{record_delimiter}** - 用于分隔元组实例的分隔符。 +- **{completion_delimiter}** - 指示生成完成的标记。 +- **{entity_specs}** - 实体类型列表。 +- **{claim_description}** - 声明应具备何种形式的描述。默认值为：`"Any claims or facts that could be relevant to information discovery."` + +有关如何更改此项的详细信息，请参阅[配置文档](../config/overview.md)。 + +### 生成社区报告 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/index/community_report.py) + +#### Tokens + +- **{input_text}** - 用于生成报告的输入文本。其中将包含实体和关系表。 + +## 查询提示 + +### 本地搜索 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/local_search_system_prompt.py) + +#### Tokens + +- **{response_type}** - 描述响应应呈现的形式。我们默认使用“multiple paragraphs”。 +- **{context_data}** - 来自 GraphRAG 索引的数据表。 + +### 全局搜索 + +[映射器提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_map_system_prompt.py) + +[归约器提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_reduce_system_prompt.py) + +[知识提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_knowledge_system_prompt.py) + +全局搜索使用 map/reduce 方法进行摘要。你可以分别独立调优这些提示。此搜索还包括调整模型训练中通用知识使用方式的能力。 + +#### Tokens + +- **{response_type}** - 描述响应应呈现的形式（仅 reducer）。我们默认使用“multiple paragraphs”。 +- **{context_data}** - 来自 GraphRAG 索引的数据表。 + +### 漂移搜索 + +[提示来源](http://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/drift_search_system_prompt.py) + +#### Tokens + +- **{response_type}** - 描述响应应呈现的形式。我们默认使用“multiple paragraphs”。 +- **{context_data}** - 来自 GraphRAG 索引的数据表。 +- **{community_reports}** - 要包含在摘要中的最相关社区报告。 +- **{query}** - 作为注入到上下文中的查询文本。 \ No newline at end of file diff --git a/docs/prompt_tuning/overview.zh.md b/docs/prompt_tuning/overview.zh.md new file mode 100644 index 0000000000..2a4f17a820 --- /dev/null +++ b/docs/prompt_tuning/overview.zh.md @@ -0,0 +1,15 @@ +# 提示词调优 ⚙️ + +本页面概述了 GraphRAG 索引引擎可用的提示词调优选项。 + +## 默认提示词 + +默认提示词是开始使用 GraphRAG 系统的最简单方式。它旨在以最少的配置开箱即用。有关用于索引和查询的各个默认提示词的更多详细信息，请参阅 [手动调优](./manual_prompt_tuning.md) 页面。 + +## 自动调优 + +自动调优利用你的输入数据和 LLM 交互来创建适应领域的提示词，以生成知识图谱。强烈建议运行它，因为它将在执行索引运行时产生更好的结果。有关如何使用它的更多详细信息，请参阅 [自动调优](auto_prompt_tuning.md) 页面。 + +## 手动调优 + +手动调优是一种高级用例。大多数用户会希望改用自动调优功能。有关如何使用手动配置的详细信息，请参阅 [手动调优](manual_prompt_tuning.md) 页面。 \ No newline at end of file diff --git a/docs/query/drift_search.zh.md b/docs/query/drift_search.zh.md new file mode 100644 index 0000000000..f847d55021 --- /dev/null +++ b/docs/query/drift_search.zh.md @@ -0,0 +1,36 @@ +# DRIFT 搜索 🔎 + +## 结合本地搜索与全局搜索 + +GraphRAG 是一种利用大型语言模型（LLM）从非结构化文本文档中创建知识图谱和摘要的技术，并利用它们来改进私有数据集上的检索增强生成（RAG）操作。它既能为大型私有非结构化文本文档集合提供全面的全局概览，也支持对细粒度、本地化信息的探索。通过使用 LLM 创建全面的知识图谱来连接并描述这些文档中包含的实体与关系，GraphRAG 利用数据的语义结构化能力，为各种复杂的用户查询生成响应。 + +DRIFT 搜索（Dynamic Reasoning and Inference with Flexible Traversal）建立在 Microsoft 的 GraphRAG 技术之上，结合了全局搜索和本地搜索的特性，使用我们的 [drift search](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/drift_search/) 方法，以一种在计算成本与结果质量之间取得平衡的方式生成详细响应。 + +## 方法论 + +

+图 1. 完整的 DRIFT 搜索层次结构，突出显示了 DRIFT 搜索流程的三个核心阶段。 +

+

+图 1. 完整的 DRIFT 搜索层次结构，突出显示了 DRIFT 搜索流程的三个核心阶段。A（Primer）：DRIFT 将用户查询与语义上最相关的前 K 个社区报告进行比较，生成一个宽泛的初始答案和后续问题，以引导进一步探索。B（Follow-Up）：DRIFT 使用本地搜索来优化查询，生成额外的中间答案和后续问题，以增强特异性，引导引擎走向上下文更丰富的信息。图中每个节点上的字形表示算法对继续执行查询扩展步骤的置信度。C（Output Hierarchy）：最终输出是一个按相关性排序的问题与答案层次结构，体现了全局洞察与本地细化之间的平衡组合，使结果既灵活又全面。

+ + +DRIFT 搜索通过在搜索过程中纳入社区信息，为本地搜索查询引入了一种新方法。这极大地扩展了查询起点的广度，并使最终答案能够检索和使用更丰富多样的事实。这一新增能力通过为本地搜索提供更全面的选项扩展了 GraphRAG 查询引擎，该选项利用社区洞察将查询细化为详细的后续问题。 + +## 配置 + +以下是 [DRIFTSearch class](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/drift_search/search.py) 的关键参数： + +* `model`：用于生成响应的语言模型聊天补全对象 +- `context_builder`：用于根据社区报告和查询信息准备上下文数据的 [context builder](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/drift_search/drift_context.py) 对象 +- `config`：用于定义 DRIFT 搜索超参数的模型。[DRIFT Config model](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/config/models/drift_search_config.py) +- `tokenizer`：用于跟踪算法预算的 token 编码器。 +- `query_state`：在 [Query State](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/drift_search/state.py) 中定义的状态对象，可用于跟踪 DRIFT 搜索实例的执行情况，以及后续问题和 [DRIFT actions](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/drift_search/action.py)。 + +## 如何使用 + +可在以下 [notebook](../examples_notebooks/drift_search.ipynb) 中找到一个 drift search 场景示例。 + +## 了解更多 + +若想更深入了解 DRIFT 搜索方法，请参阅我们的 [DRIFT Search blog post](https://www.microsoft.com/en-us/research/blog/introducing-drift-search-combining-global-and-local-search-methods-to-improve-quality-and-efficiency/) \ No newline at end of file diff --git a/docs/query/global_search.zh.md b/docs/query/global_search.zh.md new file mode 100644 index 0000000000..d23efc4cb1 --- /dev/null +++ b/docs/query/global_search.zh.md @@ -0,0 +1,73 @@ +# 全局搜索 🔎 + +## 整个数据集推理 + +基线 RAG 难以处理那些需要对整个数据集中的信息进行聚合才能组成答案的查询。像“数据中的前 5 个主题是什么？”这样的查询表现很差，因为基线 RAG 依赖于在数据集中对语义相似的文本内容进行向量搜索。查询本身并没有任何内容能引导它找到正确的信息。 + +然而，借助 GraphRAG，我们可以回答这类问题，因为由 LLM 生成的知识图谱结构能够告诉我们整个数据集的结构（以及因此得出的主题）。这使得私有数据集能够被组织成有意义的语义簇，并提前完成摘要。使用我们的[全局搜索](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/global_search/)方法时，LLM 会在响应用户查询时利用这些簇来总结这些主题。 + +## 方法论 + +```mermaid +--- +title: Global Search Dataflow +--- +%%{ init: { 'flowchart': { 'curve': 'step' } } }%% +flowchart LR + + uq[User Query] --- .1 + ch1[Conversation History] --- .1 + + subgraph RIR + direction TB + ri1[Rated Intermediate
Response 1]~~~ri2[Rated Intermediate
Response 2] -."{1..N}".-rin[Rated Intermediate
Response N] + end + + .1--Shuffled Community
Report Batch 1-->RIR + .1--Shuffled Community
Report Batch 2-->RIR---.2 + .1--Shuffled Community
Report Batch N-->RIR + + .2--Ranking +
Filtering-->agr[Aggregated Intermediate
Responses]-->res[Response] + + + + classDef green fill:#26B653,stroke:#333,stroke-width:2px,color:#fff; + classDef turquoise fill:#19CCD3,stroke:#333,stroke-width:2px,color:#fff; + classDef rose fill:#DD8694,stroke:#333,stroke-width:2px,color:#fff; + classDef orange fill:#F19914,stroke:#333,stroke-width:2px,color:#fff; + classDef purple fill:#B356CD,stroke:#333,stroke-width:2px,color:#fff; + classDef invisible fill:#fff,stroke:#fff,stroke-width:0px,color:#fff, width:0px; + class uq,ch1 turquoise; + class ri1,ri2,rin rose; + class agr orange; + class res purple; + class .1,.2 invisible; + +``` + +给定一个用户查询以及可选的对话历史，全局搜索方法会使用来自图社区层级结构中指定层级的一组由 LLM 生成的社区报告作为上下文数据，以 map-reduce 的方式生成响应。在 `map` 步骤中，社区报告会被分割为预定义大小的文本块。随后，每个文本块都会用于生成一个中间响应，其中包含一个要点列表，每个要点都附带一个数值评分，用于表示该要点的重要性。在 `reduce` 步骤中，会从中间响应中过滤并聚合一组最重要的要点，并将其作为上下文来生成最终响应。 + +全局搜索响应的质量会在很大程度上受到用于获取社区报告的社区层级结构层级选择的影响。较低的层级由于报告更详细，往往能产生更全面的响应，但由于报告数量较多，也可能增加生成最终响应所需的时间和 LLM 资源。 + + +## 配置 + +以下是 [GlobalSearch class](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/global_search/search.py) 的关键参数： + +* `model`：用于生成响应的语言模型聊天补全对象 +* `context_builder`：用于从社区报告准备上下文数据的[上下文构建器](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/global_search/community_context.py)对象 +* `map_system_prompt`：在 `map` 阶段使用的提示模板。默认模板可在 [map_system_prompt](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_map_system_prompt.py) 中找到 +* `reduce_system_prompt`：在 `reduce` 阶段使用的提示模板，默认模板可在 [reduce_system_prompt](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_reduce_system_prompt.py) 中找到 +* `response_type`：自由格式文本，用于描述期望的响应类型和格式（例如：`Multiple Paragraphs`、`Multi-Page Report`） +* `allow_general_knowledge`：将其设置为 True 会向 `reduce_system_prompt` 添加额外指令，以提示 LLM 融合数据集之外的相关现实世界知识。请注意，这可能会增加幻觉，但在某些场景下会很有用。默认值为 False +*`general_knowledge_inclusion_prompt`：如果启用了 `allow_general_knowledge`，则添加到 `reduce_system_prompt` 的指令。默认指令可在 [general_knowledge_instruction](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/global_search_knowledge_system_prompt.py) 中找到 +* `max_data_tokens`：上下文数据的 token 预算 +* `map_llm_params`：一个字典，包含将在 `map` 阶段传递给 LLM 调用的附加参数（例如 temperature、max_tokens） +* `reduce_llm_params`：一个字典，包含将传递给 `reduce` 阶段 LLM 调用的附加参数（例如 temperature、max_tokens） +* `context_builder_params`：一个字典，包含在为 `map` 阶段构建上下文窗口时传递给 [`context_builder`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/global_search/community_context.py) 对象的附加参数。 +* `concurrent_coroutines`：控制 `map` 阶段的并行度。 +* `callbacks`：可选的回调函数，可用于为 LLM 的补全流式事件提供自定义事件处理器 + +## 如何使用 + +可在以下[notebook](../examples_notebooks/global_search.ipynb)中找到一个全局搜索场景示例。 \ No newline at end of file diff --git a/docs/query/local_search.zh.md b/docs/query/local_search.zh.md new file mode 100644 index 0000000000..09a5dfb0e0 --- /dev/null +++ b/docs/query/local_search.zh.md @@ -0,0 +1,61 @@ +# 本地搜索 🔎 + +## 基于实体的推理 + +[本地搜索](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/) 方法将知识图谱中的结构化数据与输入文档中的非结构化数据相结合，在查询时使用相关实体信息增强 LLM 上下文。它非常适合回答那些需要理解输入文档中提及的特定实体的问题（例如：“洋甘菊有哪些疗愈特性？”）。 + +## 方法论 + +```mermaid +--- +title: Local Search Dataflow +--- +%%{ init: { 'flowchart': { 'curve': 'step' } } }%% +flowchart LR + + uq[User Query] ---.1 + ch1[Conversation
History]---.1 + + .1--Entity
Description
Embedding--> ee[Extracted Entities] + + ee[Extracted Entities] ---.2--Entity-Text
Unit Mapping--> ctu[Candidate
Text Units]--Ranking +
Filtering -->ptu[Prioritized
Text Units]---.3 + .2--Entity-Report
Mapping--> ccr[Candidate
Community Reports]--Ranking +
Filtering -->pcr[Prioritized
Community Reports]---.3 + .2--Entity-Entity
Relationships--> ce[Candidate
Entities]--Ranking +
Filtering -->pe[Prioritized
Entities]---.3 + .2--Entity-Entity
Relationships--> cr[Candidate
Relationships]--Ranking +
Filtering -->pr[Prioritized
Relationships]---.3 + .2--Entity-Covariate
Mappings--> cc[Candidate
Covariates]--Ranking +
Filtering -->pc[Prioritized
Covariates]---.3 + ch1 -->ch2[Conversation History]---.3 + .3-->res[Response] + + classDef green fill:#26B653,stroke:#333,stroke-width:2px,color:#fff; + classDef turquoise fill:#19CCD3,stroke:#333,stroke-width:2px,color:#fff; + classDef rose fill:#DD8694,stroke:#333,stroke-width:2px,color:#fff; + classDef orange fill:#F19914,stroke:#333,stroke-width:2px,color:#fff; + classDef purple fill:#B356CD,stroke:#333,stroke-width:2px,color:#fff; + classDef invisible fill:#fff,stroke:#fff,stroke-width:0px,color:#fff, width:0px; + class uq,ch1 turquoise + class ee green + class ctu,ccr,ce,cr,cc rose + class ptu,pcr,pe,pr,pc,ch2 orange + class res purple + class .1,.2,.3 invisible + + +``` + +给定用户查询以及可选的对话历史，本地搜索方法会从知识图谱中识别出一组与用户输入在语义上相关的实体。这些实体充当进入知识图谱的访问点，从而能够提取更多相关细节，例如相连实体、关系、实体协变量以及社区报告。此外，它还会从原始输入文档中提取与已识别实体相关的文本片段。随后，这些候选数据源会经过优先级排序和过滤，以适配预定义大小的单个上下文窗口，并用该窗口来生成对用户查询的响应。 + +## 配置 + +以下是 [LocalSearch class](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/search.py) 的关键参数： + +* `model`：用于生成响应的语言模型聊天补全对象 +* `context_builder`：用于从知识模型对象集合中准备上下文数据的 [context builder](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/mixed_context.py) 对象 +* `system_prompt`：用于生成搜索响应的提示模板。默认模板可在 [system_prompt](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/local_search_system_prompt.py) 中找到 +* `response_type`：描述所需响应类型和格式的自由文本（例如，`Multiple Paragraphs`、`Multi-Page Report`） +* `llm_params`：一个附加参数字典（例如，temperature、max_tokens），会传递给 LLM 调用 +* `context_builder_params`：一个附加参数字典，在为搜索提示构建上下文时会传递给 [`context_builder`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/mixed_context.py) 对象 +* `callbacks`：可选的回调函数，可用于为 LLM 的补全流式事件提供自定义事件处理器 + +## 如何使用 + +本地搜索场景的示例可在以下 [notebook](../examples_notebooks/local_search.ipynb) 中找到。 \ No newline at end of file diff --git a/docs/query/notebooks/overview.zh.md b/docs/query/notebooks/overview.zh.md new file mode 100644 index 0000000000..e3bc95255d --- /dev/null +++ b/docs/query/notebooks/overview.zh.md @@ -0,0 +1,14 @@ +# API 笔记本 + +- [API 概览笔记本](../../examples_notebooks/api_overview.ipynb) +- [自带向量存储](../../examples_notebooks/custom_vector_store.ipynb) + +# 查询引擎笔记本 + +有关运行 Query 的示例，请参阅以下笔记本： + +- [全局搜索笔记本](../../examples_notebooks/global_search.ipynb) +- [本地搜索笔记本](../../examples_notebooks/local_search.ipynb) +- [DRIFT 搜索笔记本](../../examples_notebooks/drift_search.ipynb) + +这些笔记本的测试数据集可在 [dataset.zip](../../data/operation_dulce/dataset.zip){:download} 中找到。 \ No newline at end of file diff --git a/docs/query/overview.zh.md b/docs/query/overview.zh.md new file mode 100644 index 0000000000..ac80c46238 --- /dev/null +++ b/docs/query/overview.zh.md @@ -0,0 +1,38 @@ +# 查询引擎 🔎 + +查询引擎是 GraphRAG 库的检索模块，并基于已完成的 [indexes](../index/overview.md) 运行。 +它负责以下任务： + +- [本地搜索](#local-search) +- [全局搜索](#global-search) +- [DRIFT 搜索](#drift-search) +- 基础搜索 +- [问题生成](#question-generation) + +## 本地搜索 + +本地搜索通过将 AI 提取的知识图谱中的相关数据与原始文档的文本块结合来生成答案。此方法适用于需要理解文档中提到的特定实体的问题（例如：洋甘菊有哪些治疗特性？）。 + +有关本地搜索工作原理的更多详细信息，请参阅 [本地搜索](local_search.md) 页面。 + +## 全局搜索 + +全局搜索通过以 map-reduce 方式搜索所有 AI 生成的社区报告来生成答案。这是一种资源密集型方法，但对于需要整体理解数据集的问题，通常能给出良好的响应（例如：本笔记本中提到的草药最重要的价值是什么？）。 + +有关此内容的更多信息，请参见 [全局搜索](global_search.md) 页面。 + +## DRIFT 搜索 + +DRIFT 搜索通过在搜索过程中纳入社区信息，为本地搜索查询引入了一种新方法。这极大地扩展了查询起点的广度，并使最终答案能够检索和使用种类丰富得多的事实。这通过为本地搜索提供一个更全面的选项来扩展 GraphRAG 查询引擎，该选项利用社区洞察将查询细化为详细的后续问题。 + +要了解有关 DRIFT 搜索的更多信息，请参阅 [DRIFT 搜索](drift_search.md) 页面。 + +## 基础搜索 + +GraphRAG 包含一个基础向量 RAG 的初步实现，以便根据你所提问题的类型轻松比较不同的搜索结果。你可以指定要包含在摘要上下文中的前 `k` 个文本单元块。 + +## 问题生成 + +此功能接收一组用户查询并生成下一批候选问题。这对于在对话中生成后续问题，或为研究人员生成一个问题列表以便更深入地挖掘数据集都很有用。 + +有关问题生成工作原理的信息，请参见 [问题生成](question_generation.md) 文档页面。 \ No newline at end of file diff --git a/docs/query/question_generation.zh.md b/docs/query/question_generation.zh.md new file mode 100644 index 0000000000..cf7cd25ef2 --- /dev/null +++ b/docs/query/question_generation.zh.md @@ -0,0 +1,23 @@ +# 问题生成 ❔ + +## 基于实体的问题生成 + +[问题生成](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/question_gen/)方法将知识图谱中的结构化数据与输入文档中的非结构化数据结合起来，以生成与特定实体相关的候选问题。 + +## 方法论 +给定一个先前用户问题列表，问题生成方法使用与[本地搜索](local_search.md)中相同的上下文构建方法来提取并优先处理相关的结构化和非结构化数据，包括实体、关系、协变量、社区报告和原始文本块。然后，这些数据记录会被整合到单个 LLM 提示中，以生成候选后续问题，这些问题代表了数据中最重要或最紧急的信息内容或主题。 + +## 配置 + +下面是[Question Generation class](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/question_gen/local_gen.py)的关键参数： + +* `model`: 用于生成响应的语言模型聊天补全对象 +* `context_builder`: 用于从知识模型对象集合准备上下文数据的[上下文构建器](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/mixed_context.py)对象，使用与本地搜索中相同的上下文构建器类 +* `system_prompt`: 用于生成候选问题的提示模板。默认模板可在[system_prompt](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/prompts/query/question_gen_system_prompt.py)中找到 +* `llm_params`: 传递给 LLM 调用的附加参数字典（例如 `temperature`、`max_tokens`） +* `context_builder_params`: 在为问题生成提示构建上下文时，传递给[`context_builder`](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/query/structured_search/local_search/mixed_context.py)对象的附加参数字典 +* `callbacks`: 可选的回调函数，可用于为 LLM 的补全流事件提供自定义事件处理器 + +## 使用方法 + +可在以下[notebook](../examples_notebooks/local_search.ipynb)中找到问题生成功能的示例。 \ No newline at end of file diff --git a/docs/visualization_guide.zh.md b/docs/visualization_guide.zh.md new file mode 100644 index 0000000000..98a120dff5 --- /dev/null +++ b/docs/visualization_guide.zh.md @@ -0,0 +1,93 @@ +# 可视化和调试你的知识图谱 + +以下分步指南将引导你完成在 graphrag 构建知识图谱之后对其进行可视化的过程。请注意，下面推荐的某些设置是基于我们自身对哪些设置效果较好的经验。你可以随意调整并探索其他设置，以获得更好的可视化体验！ + +## 1. 运行流水线 +在构建索引之前，请查看你的 `settings.yaml` 配置文件，并确保已启用 graphml 快照。 +```yaml +snapshots: + graphml: true +``` +在对你的数据运行索引流水线后，将会有一个输出文件夹（由 `storage.base_dir` 设置定义）。 + +- **输出文件夹**：包含来自 LLM 索引过程的产物。 + +## 2. 定位知识图谱 +在输出文件夹中，查找名为 `graph.graphml` 的文件。graphml 是一种标准的[文件格式](http://graphml.graphdrawing.org)，受到许多可视化工具的支持。我们建议尝试使用 [Gephi](https://gephi.org)。 + +## 3. 在 Gephi 中打开图谱 +1. 安装并打开 Gephi +2. 导航到包含各种 parquet 文件的 `output` 文件夹。 +3. 将 `graph.graphml` 文件导入 Gephi。这将得到一个相当朴素的无向图节点和边的视图。 + +

+ Gephi 生成的基础图可视化 +

+ +## 4. 安装 Leiden Algorithm 插件 +1. 前往 `Tools` -> `Plugins`。 +2. 搜索“Leiden Algorithm”。 +3. 点击 `Install` 并重启 Gephi。 + +## 5. 运行统计 +1. 在右侧的 `Statistics` 选项卡中，点击 `Average Degree` 和 `Leiden Algorithm` 的 `Run`。 + +

+ Gephi 网络概览设置视图 +

+ +2. 对于 Leiden Algorithm，调整设置： + - **质量函数**：Modularity + - **分辨率**：1 + +## 6. 按聚类为图谱着色 +1. 前往 Gephi 左上角的 `Appearance` 面板。 + +

+ Gephi 外观面板视图 +

+ +2. 选择 `Nodes`，然后选择 `Partition`，并点击右上角的调色板图标。 +3. 从下拉菜单中选择 `Cluster`。 +4. 点击 `Palette...` 超链接，然后点击 `Generate...`。 +5. 取消勾选 `Limit number of colors`，点击 `Generate`，然后点击 `Ok`。 +6. 点击 `Apply` 为图谱着色。这将根据 Leiden 发现的分区为图谱着色。 + +## 7. 按度中心性调整节点大小 +1. 在左上角的 `Appearance` 面板中，选择 `Nodes` -> `Ranking` +2. 选择右上角的 `Sizing` 图标。 +2. 选择 `Degree` 并设置： + - **最小值**：10 + - **最大值**：150 +3. 点击 `Apply`。 + +## 8. 布局图谱 +1. 在左下角的 `Layout` 选项卡中，选择 `OpenORD`。 + +

+ Gephi 布局面板视图 +

+ +2. 将 `Liquid` 和 `Expansion` 阶段设置为 50，其他全部设置为 0。 +3. 点击 `Run` 并监控进度。 + +## 9. 运行 ForceAtlas2 +1. 在布局选项中选择 `Force Atlas 2`。 + +

+ Gephi 的 ForceAtlas2 布局面板视图 +

+ +2. 调整设置： + - **缩放**：15 + - **抑制枢纽**：勾选 + - **LinLog 模式**：取消勾选 + - **防止重叠**：勾选 +3. 点击 `Run` 并等待。 +4. 当图节点看起来已经稳定且位置不再发生明显变化时，按下 `Stop`。 + +## 10. 添加文本标签（可选） +1. 在相应部分打开文本标签。 +2. 根据需要对其进行配置和调整大小。 + +现在，你的最终图谱应该已经在视觉上组织良好，并可用于分析！ \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index c26943b89c..5bb9c05738 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -62,6 +62,50 @@ nav: - Document: "data/operation_dulce/Operation Dulce v2 1 1.md" plugins: - search + - i18n: + docs_structure: suffix + fallback_to_default: true + languages: + - locale: en + default: true + name: English + build: true + - locale: zh + name: 中文 + build: true + nav_translations: + Home: 首页 + Welcome: 欢迎 + Getting Started: 快速开始 + Development Guide: 开发指南 + Indexing: 索引 + Overview: 概述 + Architecture: 架构 + Dataflow: 数据流 + Methods: 方法 + Inputs: 输入 + Outputs: 输出 + Custom Graphs: 自定义图 + Prompt Tuning: 提示词调优 + Auto Tuning: 自动调优 + Manual Tuning: 手动调优 + Query: 查询 + Global Search: 全局搜索 + Local Search: 局部搜索 + DRIFT Search: DRIFT 搜索 + Question Generation: 问题生成 + Notebooks: 笔记本 + Configuration: 配置 + Init Command: 初始化命令 + Detailed Configuration: 详细配置 + Language Model Selection: 模型选择 + CLI: CLI + Extras: 附录 + Microsoft Research Blog: 微软研究博客 + Visualization Guide: 可视化指南 + Operation Dulce: Operation Dulce + About: 关于 + Document: 文档 - exclude-search: exclude: - "data/operation_dulce/Operation Dulce v2 1 1.md"