Skip to content

feat(llm): support vector db layer V1.0 - #304

Merged
imbajin merged 75 commits into
apache:mainfrom
fantasy-lotus:vector-db
Oct 28, 2025
Merged

imbajin merged 75 commits into
apache:mainfrom
fantasy-lotus:vector-db

Conversation

@fantasy-lotus

@fantasy-lotus fantasy-lotus commented Oct 27, 2025 •

Copy link
Copy Markdown
Contributor

follow #246 to close #239 (Thanks for the contribution from @mikumifa 🔢 )


Summar

  • New Features

    • Added support for multiple vector database backends: Milvus and Qdrant alongside Faiss.
    • Introduced admin authentication system with login configuration.
    • Enhanced RAG API with reranking methods, neighbor-first option, and custom priority information.
    • Added new Gremlin output types for query results.
  • Configuration

    • Improved type safety across core configurations.
    • Added embedding dimension specifications for LLM models.
    • New vector database configuration options.
  • Documentation

    • Updated setup instructions for vector database backends and NLTK dependencies.
  • Refactoring

    • Redesigned vector index system to support pluggable backends.
    • Restructured workflow system with extensible flow abstraction.

架构序列图

sequenceDiagram
    participant User
    participant Scheduler
    participant Flow
    participant GPipeline
    participant Node
    participant Operator
    participant VectorStore

    User->>Scheduler: schedule_flow(flow_name, ...)
    Scheduler->>Flow: build_flow(...)
    Flow->>GPipeline: 创建管道
    Flow->>Node: 注册节点
    Node->>Operator: 初始化操作符
    Operator->>VectorStore: 获取向量存储实例
    
    GPipeline->>Node: run()
    Node->>Node: node_init()
    Node->>Operator: operator_schedule(data_json)
    Operator->>VectorStore: add/search/remove()
    
    Node-->>GPipeline: 返回状态
    Flow->>Flow: post_deal(pipeline)
    Flow-->>Scheduler: 返回结果
    Scheduler-->>User: 返回答案
Loading

weijinglin and others added 30 commits September 16, 2025 14:54
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Linyu <94553312+weijinglin@users.noreply.github.com>
@dosubot dosubot Bot added the size:XXL This PR changes 1000+ lines, ignoring generated files. label Oct 27, 2025
@dosubot dosubot Bot added the enhancement New feature or request label Oct 27, 2025
… improvements

Resolved conflicts by prioritizing:
- Local vector index implementations (VectorStoreBase, multi-backend support)
- Local embedding improvements (batch size handling, dynamic dimension detection)
- External flow/node architecture from apache/main
- Kept mypy and ruff configurations from local branch

All previous fixes maintained:
- Qdrant UUID fix for point IDs
- Embedding batch size auto-splitting
- Vector config UI restoration
- ImportError fixes for new vector API
…ength, signature mismatch)

- Remove unused 'os' import from graph_index_utils.py
- Fix trailing whitespace in multiple files
- Break long lines to comply with 120 char limit
- Add batch_size parameter to OllamaEmbedding.async_get_texts_embeddings for consistency
- Improve pylint comment placement for better readability

This improves the pylint score from 9.35/10 to 9.36/10
Fixed warnings:
- W0718 (broad-exception-caught): Added pylint disable comments for legitimate
  broad exception handling in error recovery paths where multiple exception
  types need to be caught
- R1711 (useless-return): Removed redundant return statement in utils.py
- R0912 (too-many-branches): Suppressed for apply_vector_engine_backend()
  which handles multiple vector DB backends
- E0401 (import-error): Suppressed for optional dependencies (pymilvus,
  qdrant_client) that may not be installed

These changes improve pylint score from 9.36/10 to 9.38/10 while maintaining
code quality and error handling robustness.
@imbajin
imbajin requested a review from Copilot October 27, 2025 13:08
"""LLM settings"""

qdrant_host: Optional[str] = os.environ.get("QDRANT_HOST", None)
qdrant_port: int = int(os.environ.get("QDRANT_PORT", "6333"))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ 类型安全问题: 这里使用了 type: ignore[arg-type],但没有充分说明原因。int(port) 转换可能在 port 为 None 或空字符串时失败。

建议改进:

if port is not None and str(port).strip():
    index_settings.milvus_port = int(port)
else:
    # Use default or handle error
    raise ValueError("Port must be provided")

这样可以避免类型检查器警告,并提供更明确的错误处理。

try:
index_settings.update_env()
except Exception: # pylint: disable=W0718
pass

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ 错误处理过于宽泛: 使用了 bare except Exception 而没有记录或重新抛出异常,这会隐藏潜在的错误。

try:
    index_settings.update_env()
except Exception:  # pylint: disable=W0718
    pass  # 静默失败,没有日志

建议:

try:
    index_settings.update_env()
except Exception as e:
    log.warning("Failed to persist settings to .env: %s", e)
    # 或者根据业务需求决定是否需要向用户显示错误

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR introduces vector database support for the HugeGraph LLM project, enabling users to choose between Faiss (default), Milvus, and Qdrant as vector storage backends. The implementation includes a new abstraction layer for vector stores, updated embedding models with batch processing support, and comprehensive configuration management.

Key Changes

  • Added VectorStoreBase abstract class and implementations for Faiss, Milvus, and Qdrant vector stores
  • Updated embedding models (OpenAI, Ollama, LiteLLM) to support dynamic dimension detection and batch processing
  • Introduced IndexConfig for managing vector database connection settings and engine selection

Reviewed Changes

Copilot reviewed 50 out of 51 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
hugegraph-llm/src/hugegraph_llm/indices/vector_index/base.py New abstract base class defining vector store interface
hugegraph-llm/src/hugegraph_llm/indices/vector_index/faiss_vector_store.py Faiss implementation of vector store
hugegraph-llm/src/hugegraph_llm/indices/vector_index/milvus_vector_store.py Milvus implementation of vector store
hugegraph-llm/src/hugegraph_llm/indices/vector_index/qdrant_vector_store.py Qdrant implementation of vector store
hugegraph-llm/src/hugegraph_llm/config/index_config.py New configuration class for vector database settings
hugegraph-llm/src/hugegraph_llm/models/embeddings/base.py Updated base embedding class with new abstract methods
hugegraph-llm/src/hugegraph_llm/models/embeddings/openai.py Enhanced OpenAI embedding with batch processing
hugegraph-llm/src/hugegraph_llm/models/embeddings/ollama.py Enhanced Ollama embedding with batch processing
hugegraph-llm/src/hugegraph_llm/models/embeddings/litellm.py Enhanced LiteLLM embedding with batch processing
hugegraph-llm/src/hugegraph_llm/utils/vector_index_utils.py Refactored to support multiple vector backends
hugegraph-llm/pyproject.toml Added optional vectordb dependencies and configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@abstractmethod
def get_all_properties(self) -> list[str]:
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring is incomplete. Consider documenting what get_all_properties returns and its purpose.

Suggested change
#TODO: finish comment
Retrieve all properties (identifiers or metadata) associated with the stored vectors.
Returns:
list[str]: A list of all properties currently stored in the vector index.

Copilot uses AI. Check for mistakes.
@abstractmethod
def save_index_by_name(self, *name: str):
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring is incomplete. Consider documenting what save_index_by_name does and its parameters.

Suggested change
#TODO: finish comment
Save the vector index to persistent storage, identified by the given name(s).
Args:
name (str): One or more names identifying the index to save.

Copilot uses AI. Check for mistakes.
self,
) -> Dict:
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring is incomplete. Consider documenting what get_vector_index_info returns and its purpose.

Suggested change
#TODO: finish comment
Retrieve information and metadata about the vector index.
Returns:
Dict: A dictionary containing details about the vector index, such as its configuration,
statistics, and other relevant metadata.

Copilot uses AI. Check for mistakes.
@abstractmethod
def from_name(embed_dim: int, *name: str) -> "VectorStoreBase":
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring is incomplete. Consider documenting what from_name does, its parameters, and return value.

Suggested change
#TODO: finish comment
Create and return an instance of a vector store by name.
Args:
embed_dim (int): The dimension of the embedding vectors.
*name (str): One or more names identifying the vector store instance.
Returns:
VectorStoreBase: An instance of the vector store corresponding to the given name(s).

Copilot uses AI. Check for mistakes.
@abstractmethod
def exist(*name: str) -> bool:
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docstring is incomplete. Consider documenting what exist checks and its parameters.

Suggested change
#TODO: finish comment
Check whether a vector index with the given name(s) exists.
Args:
*name (str): One or more names identifying the vector index to check.
Returns:
bool: True if the vector index exists, False otherwise.

Copilot uses AI. Check for mistakes.
@abstractmethod
def clean(*name: str) -> bool:
"""
#TODO: finish comment

Copilot AI Oct 27, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The return type annotation is bool but the docstring is incomplete. Clarify what the method returns and document its parameters.

Suggested change
#TODO: finish comment
Remove or clean up the vector index identified by the given name(s).
Args:
*name (str): One or more names identifying the vector index(es) to clean.
Returns:
bool: True if the cleanup was successful, False otherwise.

Copilot uses AI. Check for mistakes.

client = QdrantClient(host=host, port=int(port or 6333), api_key=api_key)
# Test if we can get collections
_ = client.get_collections()

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ 业务逻辑问题: test_api_connection 函数在连接失败时有不一致的行为。

如果 origin_call 为 None,抛出 gr.Error;如果不为 None,只是返回 -1。这种不一致的错误处理可能导致调用方难以处理错误情况。

建议统一错误处理策略:

except ImportError as e:
    msg = f"Missing dependency: {e}. Please install with: uv sync --extra vectordb"
    log.error(msg)
    if origin_call is None:
        raise gr.Error(msg) from e
    return -1  # 或者定义明确的错误码常量

@@ -1,170 +0,0 @@
# Licensed to the Apache Software Foundation (ASF) under one

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

‼️ 架构设计问题: 删除了整个 VectorIndex 类(170行代码),但 PR 中没有清楚说明迁移策略。

需要确认:

  1. 现有使用 VectorIndex 的代码是否都已迁移?
  2. 是否有向后兼容性考虑?
  3. 旧的索引文件如何处理?

建议在 PR 描述中添加迁移指南,或者提供迁移脚本。



class IndexConfig(BaseConfig):
"""LLM settings"""

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 类型注解不准确: 文档字符串写的是 "LLM settings",但这是 IndexConfig 类。

class IndexConfig(BaseConfig):
    """LLM settings"""  # 错误的文档

应该改为:

class IndexConfig(BaseConfig):
    """Vector database index settings"""


def apply_vector_engine(engine: str):
# Persist the vector engine selection
setattr(index_settings, "cur_vector_index", engine)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 可维护性问题: 使用 setattr 动态设置属性会降低代码的可读性和类型安全性。

setattr(index_settings, "cur_vector_index", engine)

建议直接赋值:

index_settings.cur_vector_index = engine

这样更清晰,且 IDE 和类型检查工具能提供更好的支持。

index_settings.qdrant_port = int(port) # type: ignore[arg-type]
# Empty string treated as None for api key
index_settings.qdrant_api_key = api_key or None

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 代码重复: 这里的错误处理逻辑与 apply_vector_engine 函数完全相同,建议提取为公共函数。

def persist_settings_safely(settings):\n    try:\n        settings.update_env()\n    except Exception as e:\n        log.warning("Failed to persist settings: %s", e)\n\nindex_settings.cur_vector_index = engine\npersist_settings_safely(index_settings)\n```

status_code = 200
elif engine == "Qdrant":
from qdrant_client import QdrantClient

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 资源管理问题: Qdrant 客户端连接后没有显式关闭,虽然 Python 有 GC,但最好显式管理资源。

建议:

elif engine == "Qdrant":
    from qdrant_client import QdrantClient
    
    client = QdrantClient(host=host, port=int(port or 6333), api_key=api_key)
    try:
        _ = client.get_collections()
        status_code = 200
    finally:
        client.close()  # 如果 API 支持的话

graph_name: Optional[str] = "hugegraph"
graph_user: Optional[str] = "admin"
graph_pwd: Optional[str] = "xxx"
graph_url: str = "127.0.0.1:8080"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ 代码风格: HugeGraphConfig 中删除了很多 Optional 类型,但某些字段仍然可能为 None。

例如 graph_space: Optional[str] = None 保留了 Optional,但其他字段如 graph_url 改成了必填。这种不一致可能导致运行时错误。

建议确认每个字段的业务语义:

  • 如果是必填配置,应该在初始化时验证
  • 如果可选,应该保持 Optional 类型

Comment thread hugegraph-llm/pyproject.toml Resolved
@dosubot dosubot Bot added the lgtm This PR has been approved by a maintainer label Oct 28, 2025
@imbajin imbajin changed the title feat(llm): vector db feat(llm): support vector db layer V1.0 Oct 28, 2025
@imbajin
imbajin merged commit 28f8575 into apache:main Oct 28, 2025
haohao0103 pushed a commit to haohao0103/incubator-hugegraph-ai that referenced this pull request Jun 30, 2026
close apache#239 apache#246

---
## Summar

* **New Features**
* Added support for multiple vector database backends: Milvus and Qdrant
alongside Faiss.
  * Introduced admin authentication system with login configuration.
* Enhanced RAG API with reranking methods, neighbor-first option, and
custom priority information.
  * Added new Gremlin output types for query results.

* **Configuration**
  * Improved type safety across core configurations.
  * Added embedding dimension specifications for LLM models.
  * New vector database configuration options.

* **Documentation**
* Updated setup instructions for vector database backends and NLTK
dependencies.

* **Refactoring**
  * Redesigned vector index system to support pluggable backends.
  * Restructured workflow system with extensible flow abstraction.
---
## 架构序列图

```mermaid
sequenceDiagram
    participant User
    participant Scheduler
    participant Flow
    participant GPipeline
    participant Node
    participant Operator
    participant VectorStore

    User->>Scheduler: schedule_flow(flow_name, ...)
    Scheduler->>Flow: build_flow(...)
    Flow->>GPipeline: 创建管道
    Flow->>Node: 注册节点
    Node->>Operator: 初始化操作符
    Operator->>VectorStore: 获取向量存储实例
    
    GPipeline->>Node: run()
    Node->>Node: node_init()
    Node->>Operator: operator_schedule(data_json)
    Operator->>VectorStore: add/search/remove()
    
    Node-->>GPipeline: 返回状态
    Flow->>Flow: post_deal(pipeline)
    Flow-->>Scheduler: 返回结果
    Scheduler-->>User: 返回答案
```

---------

Co-authored-by: Linyu <94553312+weijinglin@users.noreply.github.com>
Co-authored-by: mikumifa <1055069518@qq.com>
Co-authored-by: imbajin <jin@apache.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request lgtm This PR has been approved by a maintainer llm ml python-client size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support vector-store layer & add a vectordb support

5 participants