# Qualia

**Repository Path**: lunarlanding/qualia

## Basic Information

- **Project Name**: Qualia
- **Description**: 面 向 企 业 级 的 下 一 代 AI Agent 基 础  设 施
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qualia - 面向企业级 Java 的下一代 AI Agent 基础设施

<p align="center">
  <img src="https://img.shields.io/badge/Qualia-Enterprise--Ready-blue?style=for-the-badge&logo=java" alt="Qualia Banner">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License"></a>
  <a href="https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html"><img src="https://img.shields.io/badge/JDK-17%2B-green.svg?style=flat-square" alt="JDK"></a>
  <a href="https://maven.apache.org/"><img src="https://img.shields.io/badge/Maven-1.0.0--SNAPSHOT-blue.svg?style=flat-square" alt="Maven"></a>
  <a href="#"><img src="https://img.shields.io/badge/并发-无锁/异步-red.svg?style=flat-square" alt="Concurrency"></a>
  <a href="#"><img src="https://img.shields.io/badge/记忆-自进化-blueviolet.svg?style=flat-square" alt="Memory"></a>
  <a href="#"><img src="https://img.shields.io/badge/RAG-混合搜索-orange.svg?style=flat-square" alt="RAG"></a>
</p>

---

## 📖 目录
- [项目概览](#-项目概览)
- [核心技术支柱](#-核心技术支柱)
- [对比优势](#-对比优势)
- [核心架构](#-核心架构)
- [快速开始](#-快速开始)
- [核心代码示例](#-核心代码示例)
- [推理路径演示](#-推理路径演示)
- [模块索引](#-模块索引)
- [路线图](#-路线图)

---

## 🎯 项目概览

**Qualia** 是一个专为 Java 开发者设计的生产级、高并发 AI Agent 框架。Qualia 为企业级 AI 部署提供了所需的**稳健性、类型安全和大规模扩展性**。

Qualia 解决了现实世界 Agent 面临的三个核心挑战：
1.  **记忆衰减**: 通过多级记忆固化机制，防止 Agent 在长期任务中失去上下文。
2.  **推理不可靠**: 严格的 JSON 强制执行循环确保 API 和工具执行的可预测性。
3.  **性能瓶颈**: 异步后台工作线程处理耗时的 LLM 总结任务，保持主交互循环低延迟。

---

## 🧠 核心技术支柱

### 1. 🧬 多级自进化记忆
Qualia 通过分层架构模拟人类认知过程：
*   **L1: 感知缓冲区**: 使用 `CopyOnWriteArrayList` 实现的无锁滑动窗口消息池，用于实时交互。
*   **L2: 认知固化**: 后台 LLM 任务监控 Token 限制并执行“语义压缩”（异步总结），将海量上下文压缩为高密度知识核。
*   **L3: 长期归档**: 将向量化的摘要和事实归档到 **Milvus** 或 **InMemory** 存储中，用于跨会话的语义回溯。

### 2. 🔄 高保真 ReAct 规划引擎
*   **模式强制执行**: 内置健壮的解析器确保每一个“思考”和“行动”都符合严格的 JSON-Schema，减少幻觉导致的崩溃。
*   **原子参数验证**: 工具全元数据支持，在执行前进行精确的类型检查和必填字段验证。
*   **成本控制**: 可配置的迭代深度和 Token 监控，防止推理成本失控。

### 3. 🔍 工业级 RAG 流水线
*   **查询改写**: LLM 驱动的查询扩展，将模糊的用户问题转化为高召回率的向量搜索变体。
*   **双协议重排序**: 原生集成 **DashScope qwen3-rerank**，支持 COMPATIBLE 和 NATIVE 双协议，实现毫秒级精度。
*   **逻辑感知切分**: 提供 `MarkdownHeadingTextSplitter` 等算法套件，在分块过程中维护文档语义完整性。

---

## 📊 对比优势

| 特性 | Qualia (agent4j) | LangChain4j | Python 框架 |
| :--- | :--- | :--- | :--- |
| **并发处理** | **无锁 / 异步优先** | 多为同步 | 受 GIL 限制 |
| **记忆管理** | **3级自适应流水线** | 简单历史记录 | 基础列表 |
| **RAG 能力** | **查询改写 + 重排序** | 基础向量搜索 | 较为破碎 |
| **生产准备** | **原生 Java 性能** | 较为厚重 | 环境依赖复杂 |

---

## 🏗️ 核心架构

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as Qualia Agent
    participant M as 自适应记忆
    participant V as 向量存储
    participant L as LLM (Moark/Qwen)

    U->>A: 复杂任务输入
    rect rgb(80, 76, 76)
    Note right of A: 知识检索 (RAG)
    A->>M: 触发混合检索
    M->>V: 查询改写 & 向量搜索
    V-->>M: 排序后的事实片段
    end
    M-->>A: 注入上下文 (Profile + 摘要 + 事实)
    loop 思考循环
        A->>L: 规划请求 (Thought/Action)
        L-->>A: 结构化 JSON 方案
        alt 需要执行工具
            A->>A: 参数检查 & 工具执行
            A-->>A: 获取观察结果
        end
    end
    Note over A, M: 异步固化器
    A->>M: 提交对话片段
    M-->>V: 更新摘要索引
    A-->>U: 最终结构化决策
```
---

## 🚀 快速开始

### 安装依赖
在你的 `pom.xml` 中添加 Qualia 依赖：
```xml
<dependency>
    <groupId>cn.lunarlanding</groupId>
    <artifactId>Qualia</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>
```

### 环境配置
```powershell
# 配置 API Key (环境变量)
$env:DASHSCOPE_API_KEY="sk-..."
$env:MOARK_API_KEY="moark-..."
```

---

## 💻 核心代码示例

### 1. ChatModel 调用 (同步 & 流式)
```java
ChatModel model = new DashscopeChatModel(System.getenv("DASHSCOPE_API_KEY"));

// 同步调用
ChatResponse response = model.chat("你好，请介绍一下你自己。");
System.out.println(response.getChoices().get(0).getMessage().getContent());

// 流式调用
model.chatStream("写一首关于 Java 的诗", chunk -> {
    String content = chunk.getChoices().get(0).getMessage().getContent();
    if (content != null) System.out.print(content);
});
```

### 2. 自定义工具与 ReAct Agent
```java
// 定义工具
public class MyTool extends FunctionTool {
    public MyTool() {
        super("my_tool", "工具描述", new Parameter[]{
            new Parameter("param1", "参数描述", "string", true)
        });
    }
    @Override
    public String execute(Map<String, Object> args) {
        return "执行结果";
    }
}

// 初始化 Agent 并集成工具
ReActAgent agent = new ReActAgent(model, memory);
agent.addTool(new MyTool());
String result = agent.call("使用工具完成任务");
```

### 3. RAG 流水线
```java
// 1. 文档解析与切分
Document doc = new MarkdownDocumentParser().parse(inputStream);
List<String> chunks = new MarkdownHeadingTextSplitter().split(doc.getText());

// 2. 向量存储
VectorStore store = new InMemoryVectorStore(embeddingModel);
store.add(chunks);

// 3. 检索
Retriever retriever = new QueryRewritingRetriever(store, embeddingModel, model);
List<RetrievalResult> results = retriever.retrieve("用户问题");
```

---

## 🧩 推理路径演示

Qualia Agent 遵循严格的 **ReAct (Reasoning and Acting)** 范式。以下是一个真实的任务处理轨迹示例：

**用户输入：** "帮我计算一下 Nvidia 2024 Q3 的营收增长率，并与去年同期进行对比。"

**1. 第一次迭代 (思考 + 行动)：**
```json
{
    "type": "action",
    "thought": "用户想要了解 Nvidia 2024 Q3 的营收增长率并进行同比对比。我需要先搜索 2024 Q3 的营收数据以及 2023 Q3 的营收数据。",
    "action": {
        "name": "SearchTool",
        "arguments": {
            "query": "Nvidia 2024 Q3 revenue vs 2023 Q3 revenue"
        }
    }
}
```
**系统观察 (Observation)：**
> 搜索结果：Nvidia 2024 Q3 营收为 351 亿美元，去年同期（2023 Q3）为 181 亿美元。

**2. 第二次迭代 (思考 + 行动)：**
```json
{
    "type": "action",
    "thought": "我已经获得了两年的营收数据。现在我需要使用计算器来计算增长率：(351 - 181) / 181 * 100%。",
    "action": {
        "name": "CalculatorTool",
        "arguments": {
            "operation": "subtract",
            "num1": 351,
            "num2": 181
        }
    }
}
```
**系统观察 (Observation)：**
> 计算结果：170.00

**3. 第三次迭代 (思考 + 最终答案)：**
```json
{
    "type": "answer",
    "thought": "营收差额为 170 亿美元。接下来计算增长百分比：170 / 181 ≈ 93.9%。现在我可以回答用户了。",
    "final_answer": "Nvidia 2024 Q3 的营收为 351 亿美元，较去年同期的 181 亿美元增长了约 93.9%。这一强劲增长主要得益于数据中心业务对 AI 芯片的旺盛需求。"
}
```

---

## 📂 模块索引

| 模块 | 职责 | 核心类 |
| :--- | :--- | :--- |
| `agent` | 推理与规划 | `ReActAgent`, `Agent` |
| `llm` | 模型适配器 | `MoarkChatModel`, `DashscopeChatModel` |
| `memory` | 生命周期管理 | `ConversationSummaryMemory`, `ShortTermMemory` |
| `retriever` | 检索策略优化 | `QueryRewritingRetriever`, `RerankModel` |
| `splitter` | 数据分段 | `MarkdownHeadingTextSplitter`, `TokenTextSplitter` |
| `store` | 持久化层 | `MilvusVectorStore`, `InMemoryVectorStore` |
| `tool` | 工具定义 | `FunctionTool`, `Parameter` |

---

## 🛣️ 路线图
- [ ] **Spring Boot Starter**: 实现自动装配。
- [ ] **Agent 可视化调试面板**: 实时展示 ReAct 思考链路。
- [ ] **分布式记忆 (Redis)**: 支持跨节点记忆同步。
- [ ] **多智能体编排 (Orchestrator)**: 实现 Swarm 风格的协作逻辑。

---

## 📄 开源协议
Qualia 基于 **MIT License** 开源。