apache / apache/hugegraph-ai

[Feature] Add bounded chunk-level concurrency to graph extraction

Open
#344 1 comment 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
143
Forks
89
PR merge metrics
No merged PRs in 30d

Description

### Search before asking

- [x] I had searched in the [feature](https://github.com/apache/hugegraph-ai/issues?q=is%3Aissue+label%3A%22Feature%22) and found no similar feature requirement.

### Feature Description (功能描述)

## Feature Description

After graph extraction supports real chunk splitting, the graph extraction flow
should be able to extract chunks concurrently with a bounded concurrency limit.
The current `PropertyGraphExtract.run()` iterates over chunks serially, which
makes long documents slow when the LLM call dominates runtime.

The implementation should live in the extraction operator/flow layer, with the
demo exposing the setting to users. It should not make unbounded LLM requests.

## Current verification

- `PropertyGraphExtract.run()` loops over `chunks` with `for chunk in chunks` and calls the LLM one chunk at a time in `hugegraph-llm/src/hugegraph_llm/operators/llm_op/property_graph_extract.py:98`.
- The graph extraction demo button calls `extract_graph` once in `hugegraph-llm/src/hugegraph_llm/demo/rag_demo/vector_graph_block.py:331`.
- The RAG demo already uses a Gradio `concurrency_limit=5`, but graph extraction does not have a per-chunk concurrency control.

## Suggested scope

- Add a bounded concurrency option for chunk-level graph extraction in the operator/flow layer.
- Expose the concurrency setting from the demo after the lower-level extraction path supports it.
- Start with a conservative default, for example serial mode or a small limit, to avoid surprising LLM provider load.
- Preserve deterministic merge semantics for extracted vertices and edges as much as possible.
- Surface chunk-level errors clearly. A single failed chunk should either fail the whole extraction with context or return structured partial-failure details; do not silently drop failures.
- Consider making concurrency available only when `split_type != "document"`.

## Mermaid reference

```mermaid
flowchart TD
Text[Input documents] --> Split[ChunkSplitNode]
Split --> Flow[GraphExtractFlow]
Flow --> Queue[Bounded extraction queue]
Queue --> W1[LLM worker 1]
Queue --> W2[LLM worker 2]
Queue --> WN[LLM worker N]
W1 --> Merge[Parse, validate, merge]
W2 --> Merge
WN --> Merge
Merge --> Output[vertices, edges, chunk errors]
```

## Acceptance criteria

- The extraction flow supports a configured chunk-level concurrency limit.
- The demo exposes a clear concurrency setting or uses a documented bounded default.
- The number of simultaneous chunk extraction calls never exceeds the configured limit.
- Results from concurrent extraction are parsed and filtered with the same validation rules as serial extraction.
- Chunk failures are visible to the user.

## Suggested tests

- Unit test using a fake LLM to verify the configured concurrency limit.
- Test that serial behavior remains available.
- Test that chunk results are merged into the same `vertices` and `edges` shape as today.
- Test failure behavior for one failed chunk among several successful chunks.

## Dependencies

- This is most useful after `01-configurable-graph-extract-chunk-split.md` is implemented.

### Are you willing to submit a PR?

- [ ] Yes I am willing to submit a PR!

### Code of Conduct

- [x] I agree to follow this project's [Code of Conduct](https://www.apache.org/foundation/policies/conduct)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.