Repository navigation
feat(llm): support vector db layer V1.0 - #304
Conversation
… 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.
| """LLM settings""" | ||
|
|
||
| qdrant_host: Optional[str] = os.environ.get("QDRANT_HOST", None) | ||
| qdrant_port: int = int(os.environ.get("QDRANT_PORT", "6333")) |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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)
# 或者根据业务需求决定是否需要向用户显示错误There was a problem hiding this comment.
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
VectorStoreBaseabstract 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
IndexConfigfor 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 |
There was a problem hiding this comment.
The docstring is incomplete. Consider documenting what get_all_properties returns and its purpose.
| #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. |
| @abstractmethod | ||
| def save_index_by_name(self, *name: str): | ||
| """ | ||
| #TODO: finish comment |
There was a problem hiding this comment.
The docstring is incomplete. Consider documenting what save_index_by_name does and its parameters.
| #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. |
| self, | ||
| ) -> Dict: | ||
| """ | ||
| #TODO: finish comment |
There was a problem hiding this comment.
The docstring is incomplete. Consider documenting what get_vector_index_info returns and its purpose.
| #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. |
| @abstractmethod | ||
| def from_name(embed_dim: int, *name: str) -> "VectorStoreBase": | ||
| """ | ||
| #TODO: finish comment |
There was a problem hiding this comment.
The docstring is incomplete. Consider documenting what from_name does, its parameters, and return value.
| #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). |
| @abstractmethod | ||
| def exist(*name: str) -> bool: | ||
| """ | ||
| #TODO: finish comment |
There was a problem hiding this comment.
The docstring is incomplete. Consider documenting what exist checks and its parameters.
| #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. |
| @abstractmethod | ||
| def clean(*name: str) -> bool: | ||
| """ | ||
| #TODO: finish comment |
There was a problem hiding this comment.
The return type annotation is bool but the docstring is incomplete. Clarify what the method returns and document its parameters.
| #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. |
|
|
||
| client = QdrantClient(host=host, port=int(port or 6333), api_key=api_key) | ||
| # Test if we can get collections | ||
| _ = client.get_collections() |
There was a problem hiding this comment.
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 | |||
There was a problem hiding this comment.
VectorIndex 类(170行代码),但 PR 中没有清楚说明迁移策略。
需要确认:
- 现有使用
VectorIndex的代码是否都已迁移? - 是否有向后兼容性考虑?
- 旧的索引文件如何处理?
建议在 PR 描述中添加迁移指南,或者提供迁移脚本。
|
|
||
|
|
||
| class IndexConfig(BaseConfig): | ||
| """LLM settings""" |
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
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 | ||
|
|
There was a problem hiding this comment.
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 | ||
|
|
There was a problem hiding this comment.
建议:
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" |
There was a problem hiding this comment.
HugeGraphConfig 中删除了很多 Optional 类型,但某些字段仍然可能为 None。
例如 graph_space: Optional[str] = None 保留了 Optional,但其他字段如 graph_url 改成了必填。这种不一致可能导致运行时错误。
建议确认每个字段的业务语义:
- 如果是必填配置,应该在初始化时验证
- 如果可选,应该保持
Optional类型
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>
follow #246 to close #239 (Thanks for the contribution from @mikumifa 🔢 )
Summar
New Features
Configuration
Documentation
Refactoring
架构序列图
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: 返回答案