从混乱到清晰：RAGbits项目示例代码组织结构优化指南
项目地址: https://gitcode.com/GitHub_Trending/ra/ragbits 引言：你是否也面临这些示例代码困境？
在开发GenAI（生成式人工智能）应用时，示例代码往往是开发者入门的第一扇门。然而，许多项目的示例代码却常常陷入以下困境：
- 结构混乱：文件随意放置，难以理解各部分之间的关系
- 命名不规范：函数和类命名模糊，功能难以推断
- 缺乏一致性：不同模块的代码风格迥异，增加理解成本
- 文档缺失：示例代码缺少必要注释，新手难以快速上手
- 扩展性差：代码紧耦合，难以根据需求进行修改和扩展
如果你正在使用RAGbits项目，或者计划基于RAGbits构建GenAI应用，本文将为你提供一套全面的示例代码组织结构优化方案。通过本文的学习，你将能够：
- 理解RAGbits项目现有示例代码的结构和问题
- 掌握模块化组织示例代码的核心原则
- 学会使用设计模式提升代码的可维护性和可扩展性
- 建立统一的代码风格和文档规范
- 通过具体案例实践优化技巧
RAGbits项目示例代码现状分析
RAGbits作为一个用于快速开发GenAI应用的构建块集合，其示例代码分布在多个目录中，涵盖了代理（agents）、聊天（chat）、核心功能（core）、文档搜索（document-search）和评估（evaluate）等多个方面。
现有结构概览
examples/
├── agents/
│ ├── a2a/
│ │ ├── agent_orchestrator.py
│ │ ├── agent_orchestrator_with_tools.py
│ │ ├── city_explorer_agent.py
│ │ ├── flight_agent.py
│ │ ├── hotel_agent.py
│ │ └── run_orchestrator.py
│ ├── mcp/
│ │ ├── local.py
│ │ ├── sse.py
│ │ └── streamable_http.py
│ ├── openai_native_tool_use.py
│ └── tool_use.py
├── chat/
│ ├── chat.py
│ ├── offline_chat.py
│ └── recontextualize_message.py
├── core/
│ ├── audit/
│ ├── llms/
│ └── prompt/
├── document-search/
│ ├── basic.py
│ ├── chroma.py
│ ├── images/
│ ├── multimodal.py
│ ├── pgvector.py
│ ├── qdrant.py
│ └── weaviate_.py
└── evaluate/
├── dataset-generator/
└── document-search/
主要问题分析
通过对RAGbits项目示例代码的深入分析，我们发现存在以下主要问题：
1. 命名不规范
许多文件和函数命名过于简单，无法准确反映其功能。例如：
# 文件名: basic.py
def main() -> None:
"""Run the example."""
embedder = LiteLLMEmbedder(
model_name="text-embedding-3-small",
)
# ...
basic.py这个文件名没有明确说明该示例的具体内容，main()函数也没有提供足够的信息来了解其功能。
2. 结构层次不清晰
示例代码的目录结构虽然按照功能模块进行了划分，但在每个模块内部，文件的组织仍然缺乏明确的层次关系。例如，agents目录下的文件既有代理协调器，又有具体的代理实现，没有进一步的分类。
3. 代码复用性低
不同示例之间存在大量重复代码。例如，在多个示例中都出现了创建LLM客户端、设置日志等相似代码，但没有进行抽象和复用。
4. 文档和注释不足
虽然部分文件有简单的文档字符串，但大多数函数和类缺乏详细的注释说明，特别是对于复杂逻辑的解释不足。例如：
async def create_agent_tasks(self, message: str) -> str:
"""
Creates tasks for remote agents based on the input message.
Args:
message: The user query to route to agents
Returns:
JSON string of created tasks
"""
prompt_input = RoutingPromptInput(message=message, agents=self._list_remote_agents())
prompt = self._routing_prompt(prompt_input)
response = await self.llm.generate(prompt)
tasks = json.loads(response)
self._current_tasks = [RemoteAgentTask(**task) for task in tasks]
return json.dumps(
{
"status": "success",
"task_count": len(self._current_tasks),
"tasks": [task.dict() for task in self._current_tasks],
}
)
这段代码虽然有基本的文档字符串，但对于RoutingPromptInput的结构、_routing_prompt的作用以及返回JSON的格式都没有详细说明，增加了理解难度。
5. 缺乏一致性
不同示例代码在命名规范、代码风格和组织结构上存在较大差异。例如，有些示例使用类来组织代码，而有些则全部使用函数；有些示例有详细的类型注解，而有些则没有。
示例代码组织结构优化原则
针对上述问题，我们提出以下示例代码组织结构优化原则：
1. 模块化原则
将示例代码按照功能划分为清晰的模块，每个模块专注于解决特定领域的问题。模块之间应该保持低耦合，通过明确定义的接口进行通信。
2. 单一职责原则
每个文件和函数应该只负责一项具体功能。这样可以提高代码的可读性和可维护性，也便于测试和调试。
3. 一致性原则
在整个项目中保持一致的代码风格、命名规范和组织结构。这包括文件命名、函数命名、缩进方式、注释风格等。
4. 可扩展性原则
设计示例代码时应该考虑未来的扩展需求。通过使用接口、抽象类等设计模式，使代码能够轻松适应新的功能和变化。
5. 文档化原则
为所有示例代码提供清晰、详细的文档，包括用途说明、使用方法、参数说明和返回值解释等。这对于新手开发者尤为重要。
RAGbits示例代码组织结构优化实践
基于以上原则，我们对RAGbits项目的示例代码组织结构进行全面优化。
1. 目录结构重构
优化后的目录结构如下：
examples/
├── agents/
│ ├── a2a/
│ │ ├── core/
│ │ │ ├── agent_orchestrator.py
│ │ │ └── remote_agent_task.py
│ │ ├── prompts/
│ │ │ ├── routing_prompt.py
│ │ │ └── summarization_prompt.py
│ │ ├── agents/
│ │ │ ├── city_explorer_agent.py
│ │ │ ├── flight_agent.py
│ │ │ └── hotel_agent.py
│ │ ├── utils/
│ │ │ └── server_utils.py
│ │ └── run_orchestrator_demo.py
│ ├── mcp/
│ │ ├── core/
│ │ ├── examples/
│ │ │ ├── local_agent_demo.py
│ │ │ ├── sse_agent_demo.py
│ │ │ └── streamable_http_agent_demo.py
│ │ └── utils/
│ └── tool_use/
│ ├── examples/
│ │ ├── openai_native_tool_use_demo.py
│ │ └── basic_tool_use_demo.py
│ └── tools/
│ └── weather_tool.py
├── chat/
│ ├── core/
│ │ ├── chat_client.py
│ │ └── message_processor.py
│ ├── examples/
│ │ ├── basic_chat_demo.py
│ │ ├── offline_chat_demo.py
│ │ └── recontextualize_message_demo.py
│ └── utils/
├── document_search/
│ ├── core/
│ │ ├── document_ingestor.py
│ │ └── document_searcher.py
│ ├── examples/
│ │ ├── basic_document_search_demo.py
│ │ ├── chroma_vector_store_demo.py
│ │ ├── multimodal_search_demo.py
│ │ ├── pgvector_store_demo.py
│ │ ├── qdrant_vector_store_demo.py
│ │ └── weaviate_vector_store_demo.py
│ ├── stores/
│ │ ├── chroma_store.py
│ │ ├── pgvector_store.py
│ │ ├── qdrant_store.py
│ │ └── weaviate_store.py
│ └── utils/
└── evaluate/
├── document_search/
│ ├── core/
│ │ ├── evaluator.py
│ │ └── optimizer.py
│ ├── examples/
│ │ ├── basic_evaluation_demo.py
│ │ └── optimization_demo.py
│ └── configs/
└── dataset_generator/
├── core/
├── examples/
└── configs/
2. 命名规范优化
采用以下命名规范：
- 目录名：使用小写字母，多个单词用下划线连接（snake_case）
- 文件名：使用小写字母，多个单词用下划线连接，以"_demo.py"结尾的文件表示可运行的示例
- 类名：使用首字母大写的驼峰式命名（PascalCase）
- 函数和变量名：使用小写字母，多个单词用下划线连接（snake_case）
- 常量：使用全大写字母，多个单词用下划线连接
3. 模块化代码示例
以A2A代理协调器为例，优化后的代码结构如下：
3.1 核心模块
# agents/a2a/core/agent_orchestrator.py
import json
from typing import List, Dict, AsyncGenerator, TypeVar
from pydantic import BaseModel
from ragbits.agents import Agent, AgentOptions, AgentResult, ToolCallResult
from ragbits.core.llms import LiteLLM
from ragbits.core.prompt import ChatFormat, Prompt
from ..prompts.routing_prompt import RoutingPrompt, RoutingPromptInput
from ..prompts.summarization_prompt import SummarizationPrompt, SummarizationPromptInput
from .remote_agent_task import RemoteAgentTask
OptionsT = TypeVar("OptionsT", bound=AgentOptions)
class AgentOrchestrator(Agent):
"""
Coordinates querying and aggregating responses from multiple remote agents
using tools for routing and task execution.
This class manages the lifecycle of agent tasks, including task creation,
execution, and result summarization. It uses a large language model to
determine which agents should handle specific tasks and how to combine their results.
"""
def __init__(
self,
llm: LiteLLM,
routing_prompt: RoutingPrompt,
summarization_prompt: SummarizationPrompt,
timeout: float = 20.0,
*,
history: ChatFormat | None = None,
keep_history: bool = False,
default_options: AgentOptions[OptionsT] | None = None,
):
"""
Initialize the agent orchestrator with necessary components.
Args:
llm: The large language model to use for task routing and result summarization
routing_prompt: Prompt template for determining which agents should handle tasks
summarization_prompt: Prompt template for combining agent results
timeout: Timeout in seconds for HTTP requests to remote agents
history: Chat history to maintain context between interactions
keep_history: Whether to retain chat history between orchestrator runs
default_options: Default options for agent execution
"""
super().__init__(
llm=llm,
prompt=None,
history=history,
keep_history=keep_history,
tools=[self.create_agent_tasks, self.execute_agent_task, self.summarize_agent_results],
default_options=default_options,
)
self._timeout = timeout
self._routing_prompt = routing_prompt
self._summarization_prompt = summarization_prompt
self._remote_agents: Dict[str, Dict] = {}
self._current_tasks: List[RemoteAgentTask] = []
self._current_results: List[AgentResult] = []
def add_remote_agent(self, host: str, port: int, protocol: str = "http") -> None:
"""
Discovers and registers a remote agent by fetching its agent card metadata.
Agent cards contain information about the agent's capabilities, endpoints,
and supported operations, enabling the orchestrator to route tasks appropriately.
Args:
host: The hostname or IP address of the remote agent
port: The port on which the remote agent server is running
protocol: The communication protocol (http or https). Defaults to "http"
"""
# ... implementation ...
async def create_agent_tasks(self, message: str) -> str:
"""
Creates tasks for remote agents based on the input message.
Uses the configured LLM and routing prompt to analyze the user query and
determine which agents should handle which sub-tasks.
Args:
message: The user query to route to appropriate agents
Returns:
JSON string containing the created tasks with agent URLs and parameters
"""
# ... implementation ...
async def execute_agent_task(self, task_index: int) -> str:
"""
Executes a specific task from the current task list.
Sends the task parameters to the designated remote agent, executes the task,
and stores the result for later summarization.
Args:
task_index: Index of the task to execute in the current task list
Returns:
JSON string containing the execution result and status
"""
# ... implementation ...
async def summarize_agent_results(self, message: str) -> str:
"""
Summarizes all collected agent results into a coherent response.
Uses the configured LLM and summarization prompt to combine results from
multiple agents into a single, unified response to the original user query.
Args:
message: The original user message to provide context for summarization
Returns:
The summarized response combining all agent results
"""
# ... implementation ...
def _execute_single_task(self, agent_url: str, params: dict) -> AgentResult:
"""
Executes a single task on a remote agent.
Private helper method that handles the actual HTTP communication with
remote agents and processes their responses.
Args:
agent_url: The URL of the remote agent to execute the task
params: The parameters to send to the remote agent
Returns:
An AgentResult object containing the task execution result
"""
# ... implementation ...
def _list_remote_agents(self) -> List[dict]:
"""
Lists metadata of all registered remote agents in a format suitable for routing.
Private helper method that prepares agent information for the routing prompt.
Returns:
A list of dictionaries describing each remote agent's capabilities
"""
# ... implementation ...
3.2 提示模板模块
# agents/a2a/prompts/routing_prompt.py
from pydantic import BaseModel
from ragbits.core.prompt import Prompt
class RoutingPromptInput(BaseModel):
"""
Input model for the agent routing prompt.
Contains the user message and information about available agents to help
the LLM determine how to route the query.
"""
message: str
"""The user query to be routed to appropriate agents"""
agents: list
"""List of available agents with their capabilities and endpoints"""
class RoutingPrompt(Prompt[RoutingPromptInput]):
"""
Prompt template for routing a user message to appropriate agents.
This prompt instructs the LLM to analyze a user query and determine which
remote agents should handle which aspects of the query, generating structured
tasks for each agent.
"""
system_prompt = """
You are a router agent. Your task is to read the user's message and output a list of tasks in JSON format.
Each task must include:
- agent_url: The base URL of the agent that should handle the task.
- tool: The name of the skill/tool to call on that agent.
- parameters: A dictionary with input argument which is just the task for the agent to answer.
Currently available agents and their tools:
{{ agents }}
Return your output as a **JSON list** of tasks. Your response must be only the JSON list (e.g. starting with `[`).
If there are multiple tasks in the user request, return multiple entries in the list.
Example:
User: "Check weather in Paris and get a summary of recent news from France"
Output:
[
{
"agent_url": "http://weather-agent:8000",
"tool": "get_weather",
"parameters": { "input": "What is the weather in Paris?" }
},
{
"agent_url": "http://news-agent:8001",
"tool": "get_news_summary",
"parameters": { "input": "What are the news in France?" }
}
]
"""
user_prompt = "{{ message }}"
3.3 示例运行文件
# agents/a2a/run_orchestrator_demo.py
"""
RAGbits Agents Example: A2A Orchestration Demonstration
This example demonstrates how to use the `AgentOrchestrator` to route a complex user query
across multiple specialized agents (e.g., hotel and flight). Each agent is hosted as an HTTP server
and can be invoked remotely using the A2A protocol.
The orchestrator automatically routes sub-tasks to the correct agent based on the content of the request.
To execute this script, run:
```bash
uv run examples/agents/a2a/run_orchestrator_demo.py
"""
/// script
requires-python = ">=3.10"
dependencies = [
"ragbits-core",
"ragbits-agents[a2a]",
]
///
import asyncio import threading from typing import AsyncGenerator
from uvicorn import Server
from ragbits.agents.a2a.server import create_agent_server from ragbits.core.llms import LiteLLM from ragbits.core.prompt import Prompt
from .core.agent_orchestrator import AgentOrchestrator from .prompts.routing_prompt import RoutingPrompt, RoutingPromptInput from .prompts.summarization_prompt import SummarizationPrompt, SummarizationPromptInput from .agents.flight_agent import flight_agent, FlightPromptInput from .agents.hotel_agent import hotel_agent, HotelPromptInput from .utils.server_utils import wait_for_server_to_start
async def main() -> None: """ Sets up a LiteLLM-powered AgentOrchestrator with two remote agents and sends a travel planning query.
This demonstration:
1. Starts flight and hotel agent servers in background threads
2. Creates an AgentOrchestrator with routing and summarization capabilities
3. Registers the remote agents with the orchestrator
4. Sends a travel planning query to the orchestrator
5. Prints the orchestrated response combining results from both agents
"""
# Start flight agent server
flight_agent_card = await flight_agent.get_agent_card(
name="Flight Info Agent",
description="Provides available flight information between two cities.",
port=8000
)
flight_agent_server = create_agent_server(flight_agent, flight_agent_card, FlightPromptInput)
# Start hotel agent server
hotel_agent_card = await hotel_agent.get_agent_card(
name="Hotel Recommendation Agent",
description="Recommends hotels for a given city and travel dates.",
port=8001
)
hotel_agent_server = create_agent_server(hotel_agent, hotel_agent_card, HotelPromptInput)
# Wait for both servers to start
await asyncio.gather(
wait_for_server_to_start(flight_agent_server),
wait_for_server_to_start(hotel_agent_server)
)
# Initialize LLM with structured output capability
llm = LiteLLM(
model_name="gpt-4o-2024-08-06",
use_structured_output=True,
)
# Create orchestrator with routing and summarization prompts
orchestrator = AgentOrchestrator(
llm=llm,
routing_prompt=RoutingPrompt,
summarization_prompt=SummarizationPrompt
)
# Register remote agents
orchestrator.add_remote_agent("127.0.0.1", 8000) # Flight agent
orchestrator.add_remote_agent("127.0.0.1", 8001) # Hotel agent
# Send travel planning query to orchestrator
user_query = "I want to travel from New York to Paris. Find me hotel and flight options please."
print(f"Sending query to orchestrator: {user_query}")
response = await orchestrator.run(user_query)
print(f"\nOrchestrated response:\n{response.content}")
if name == "main": asyncio.run(main())
### 4. 文档搜索示例优化
文档搜索模块的优化主要集中在分离关注点和提高代码复用性：
```python
# document_search/core/document_searcher.py
from typing import List, Optional
from ragbits.core.embeddings.dense import LiteLLMEmbedder
from ragbits.core.vector_stores import VectorStore, SearchResult
from ragbits.document_search.documents.document import DocumentMeta
class DocumentSearcher:
"""
A component for searching through ingested documents using vector similarity.
This class provides a high-level interface for:
- Initializing vector stores with appropriate embedders
- Ingesting documents into the vector store
- Searching for relevant documents based on query similarity
"""
def __init__(self, vector_store: VectorStore):
"""
Initialize the DocumentSearcher with a vector store.
Args:
vector_store: The vector store to use for document storage and retrieval
"""
self.vector_store = vector_store
async def ingest(self, documents: List[DocumentMeta]) -> None:
"""
Ingest documents into the vector store.
Args:
documents: List of DocumentMeta objects to ingest
"""
await self.vector_store.add_documents(documents)
async def search(
self,
query: str,
limit: int = 3,
score_threshold: Optional[float] = None
) -> List[SearchResult]:
"""
Search for documents relevant to the given query.
Args:
query: The search query string
limit: Maximum number of results to return (default: 3)
score_threshold: Minimum similarity score for results (optional)
Returns:
List of SearchResult objects containing relevant documents
"""
return await self.vector_store.search(
query=query,
limit=limit,
score_threshold=score_threshold
)
# document_search/examples/basic_document_search_demo.py
"""
RAGbits Document Search Example: Basic Search Functionality
This example demonstrates how to use the DocumentSearcher class to:
1. Initialize a vector store with an appropriate embedder
2. Ingest sample documents
3. Perform similarity search based on a query
To run the script, execute:
```bash
uv run examples/document_search/examples/basic_document_search_demo.py
"""
/// script
requires-python = ">=3.10"
dependencies = [
"ragbits-document-search",
"ragbits-core",
]
///
import asyncio
from ragbits.core.audit import set_trace_handlers from ragbits.core.embeddings.dense import LiteLLMEmbedder from ragbits.core.vector_stores.in_memory import InMemoryVectorStore from ragbits.document_search.documents.document import DocumentMeta
from ..core.document_searcher import DocumentSearcher
Set up tracing to CLI for demonstration purposes
set_trace_handlers("cli")
Sample documents to ingest
sample_documents = [ DocumentMeta.from_literal( """ RIP boiled water. You will be mist. """ ), DocumentMeta.from_literal( """ Why doesn't James Bond fart in bed? Because it would blow his cover. """ ), DocumentMeta.from_literal( """ Why programmers don't like to swim? Because they're scared of the floating points. """ ), DocumentMeta.from_literal( """ This one is completely unrelated. """ ), ]
async def run_document_search_demo() -> None: """ Run the basic document search demonstration.
This function:
1. Creates an embedder using LiteLLM with text-embedding-3-small
2. Initializes an in-memory vector store
3. Creates a DocumentSearcher with the vector store
4. Ingests sample documents
5. Searches for documents related to the query
6. Prints the search results
"""
# Initialize components
embedder = LiteLLMEmbedder(
model_name="text-embedding-3-small",
)
vector_store = InMemoryVectorStore(embedder=embedder)
document_searcher = DocumentSearcher(vector_store=vector_store)
# Ingest documents
print("Ingesting sample documents...")
await document_searcher.ingest(sample_documents)
# Perform search
query = "I'm boiling my water and I need a joke"
print(f"\nSearching for: '{query}'")
results = await document_searcher.search(query)
# Display results
print(f"\nFound {len(results)} relevant documents:")
for i, result in enumerate(results, 1):
print(f"\nResult {i} (Score: {result.score:.4f}):")
print(result.document.content.strip())
if name == "main": asyncio.run(run_document_search_demo())
## 优化效果对比
通过上述优化，RAGbits项目的示例代码在以下几个方面得到了显著改善：
### 1. 代码结构清晰度
| 优化前 | 优化后 |
|--------|--------|
| 文件组织结构较为混乱，难以快速定位功能 | 清晰的模块化结构，按功能划分明确的目录层次 |
| 命名简单模糊，如`basic.py`、`main()` | 命名规范统一，如`basic_document_search_demo.py`、`run_document_search_demo()` |
| 代码复用性低，重复代码多 | 公共功能抽象为独立模块，提高代码复用 |
### 2. 可维护性
优化后的代码采用了更清晰的结构和更详细的文档，使维护变得更加容易。例如，当需要修改文档搜索的逻辑时，只需关注`document_search/core/document_searcher.py`文件，而不需要在多个示例文件中进行相同的修改。
### 3. 可扩展性
通过引入接口和抽象类，优化后的代码更容易扩展以支持新功能。例如，要添加新的向量存储类型，只需实现VectorStore接口并在相应的示例文件中使用，而不需要修改核心搜索逻辑。
### 4. 学习曲线
详细的文档和注释、一致的代码风格以及清晰的结构，大大降低了新手开发者的学习曲线。每个示例文件都有明确的用途说明和使用方法，使新用户能够快速上手。
## 总结与最佳实践建议
通过对RAGbits项目示例代码组织结构的全面优化，我们不仅解决了现有问题，还建立了一套可推广的最佳实践：
### 1. 项目结构最佳实践
- **按功能模块划分目录**：将相关功能组织在同一目录下，提高代码的内聚性
- **建立清晰的层次结构**：在每个模块内部，进一步划分为core、examples、utils等子目录
- **分离关注点**：将核心逻辑、数据模型、工具函数和示例代码明确分离
### 2. 代码组织最佳实践
- **单一职责原则**：每个类和函数只负责一项功能
- **依赖注入**：通过构造函数注入依赖，提高代码的灵活性和可测试性
- **接口抽象**：对可能有多种实现的组件定义接口，如VectorStore
- **常量和配置外置**：将常量和配置参数集中管理，便于维护
### 3. 文档和命名最佳实践
- **一致的命名规范**：遵循统一的命名约定，提高代码可读性
- **详细的文档字符串**：为所有公共类、函数提供完整的文档字符串
- **示例用途说明**：每个示例文件开头明确说明其用途和运行方法
- **代码注释**：对复杂逻辑添加必要的注释说明
### 4. 示例代码编写建议
- **专注于单一概念**：每个示例文件只演示一个核心概念或功能
- **提供完整可运行代码**：确保每个示例都可以独立运行，不需要修改
- **包含必要的注释**：解释关键步骤和设计决策
- **使用真实场景**：示例应反映实际应用场景，提高实用性
通过遵循这些最佳实践，不仅可以提高代码质量和可维护性，还能为项目的新用户提供更好的学习体验，促进项目的健康发展和广泛应用。
## 后续优化方向
虽然本次优化已经取得了显著效果，但仍有一些潜在的优化方向值得探索：
1. **引入更多设计模式**：如工厂模式用于创建不同类型的向量存储，观察者模式用于事件处理等
2. **完善测试覆盖**：为示例代码添加单元测试和集成测试
3. **创建交互式示例**：使用Jupyter Notebook提供交互式示例，增强学习体验
4. **多语言支持**：为不同编程语言提供相应的示例代码
通过持续改进和优化，RAGbits项目的示例代码可以成为GenAI应用开发的典范，帮助更多开发者快速构建高质量的生成式人工智能应用。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
