内容
# 佩索阿：本地、与大语言模型无关的 AI 代理基础设施
<p align="center">
<img src="https://img.shields.io/github/license/tiagomonteiro0715/pessoa" alt="许可证"/>
<img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+"/>
<img src="https://img.shields.io/github/last-commit/tiagomonteiro0715/pessoa" alt="最新提交"/>
<img src="https://img.shields.io/github/stars/tiagomonteiro0715/pessoa" alt="星星"/>
<img src="https://img.shields.io/github/forks/tiagomonteiro0715/pessoa" alt="分支"/>
</p>
## 项目演示
## 目录
- [为什么这个项目被称为“佩索阿”？](#为什么这个项目被称为“佩索阿”)
- [如何使用这个项目？](#如何使用这个项目)
- [技术栈、架构和项目树](#技术栈、架构和项目树)
- [运行](#运行)
- [配置](#配置)
- [使用克劳德技能作为角色](#使用克劳德技能作为角色)
- [贡献](#贡献)
- [构建工具](#构建工具)
- [联系](#联系)
- [许可证](#许可证)
## 为什么这个项目被称为“佩索阿”？
以 **费尔南多·安东尼奥·诺盖拉·德·塞布拉·佩索阿**（1888 年 6 月 13 日 - 1935 年 11 月 30 日）命名，他被认为是 20 世纪最重要的葡萄牙文学人物之一，也是葡萄牙语中最伟大的诗人。*Pessoa* 在葡萄牙语中也意味着“人”。
## 如何使用这个项目？
- **Streamlit 聊天界面** — 多聊天侧边栏（搜索、内联重命名、日期分组、更多操作）、流式答案、*停止生成*、动画打字指示器、活动聊天上的流式点、图像/音频附件、可选的网络/天气查找。
- **OpenAPI HTTP API** ([src/API/server.py](src/API/server.py)) — FastAPI 包装器，暴露 `/chat`、`/memory/search` 和 `/health`；Swagger UI 在 `/docs`，OpenAPI 3.0 规范在 `/openapi.json`。
- **MCP 服务器** ([src/MCP/server.py](src/MCP/server.py)) — 标准的模型上下文协议，带有 `chat` 和 `search_memory` 工具，任何 MCP 客户端（克劳德桌面版等）都可以调用。
## 技术栈、架构和项目树
```text
pessoa/
├── README.md
├── LICENSE
├── pyproject.toml # uv-locked Python 依赖项
├── main.py # 启动器：--skill 标志、Ollama 启动、运行 Streamlit
├── tox.ini # tox 会话 — Python 版本矩阵
├── noxfile.py # nox 会话 — 每层测试（合约 / 端到端 / 限制 / mcp）
├── src/
│ ├── chat.py # 引擎：模型配置、内存、流式处理、技能组合
│ ├── system_prompt.py # 基于 pt-PT 的基本角色
│ ├── app.py # Streamlit 聊天界面
│ ├── styles.css # 暗色主题 + 侧边栏样式
│ ├── API/
│ │ └── server.py # FastAPI / OpenAPI HTTP 包装器
│ └── MCP/
│ └── server.py # 标准的 MCP 服务器（聊天、搜索内存工具）
├── skills/
│ └── code-reviewer.md # 示例克劳德技能（pt-PT）
├── tests/
│ ├── test_api_contract.py # 模式 + 端点，无 LLM
│ ├── test_api_e2e.py # 针对 Ollama 的真实生成
│ ├── test_api_limits.py # 并发扫描（需要服务器运行）
│ └── test_mcp.py # MCP 工具列表 + 调用
└── pessoa_qdrant/ # 本地 Qdrant 矢量存储（运行时数据）
```
## 运行
### 安装依赖项
```bash
git clone https://github.com/tiagomonteiro0715/pessoa
cd pessoa
uv python install 3.13
uv python pin 3.13
uv sync
```
### 启动 Streamlit 界面
```bash
ollama serve (在单独的终端中)
uv run python main.py
```
### 运行 HTTP API
```bash
uv run python src/API/server.py
```
### 运行 MCP 服务器
```bash
uv run python src/MCP/server.py
```
## 配置
[src/chat.py](src/chat.py) 顶部的可调参数：
| 设置 | 默认值 | 备注 |
|---------|---------|-------|
| `MODEL` | `gemma4:e2b` | 聊天模型。 |
| `EMBED_MODEL` | `nomic-embed-text` | 内存搜索的嵌入。 |
| `NUM_CTX` | `8192` | 上下文窗口。越大 = 更多上下文，但更慢/更重。 |
| `KEEP_ALIVE` | `45m` | Ollama 在内存中保持模型温暖的时间。 |
| `USER_ID` | `pessoa` | mem0 用户 ID；更改以保持独立的内存存储。 |
| `STOP` | Llama 停止标记 | 对 Gemma 无效；如果切换模型系列，请调整。 |
## 使用克劳德技能作为角色
克劳德技能只是针对大语言模型的文本指令。佩索阿已经使用 `{"role": "system", "content": …}` 块构建了其系统提示（pt-PT 角色、回忆内存、可选的网络/天气事实）。这样，技能就可以作为另一个块插入堆栈中。
## 贡献
- **发现了错误，或注意到 pt-PT 提示有问题？** 打开问题或发送电子邮件给我。
- **有值得与存储库一起发布的技能文件吗？** 将其放在 `skills/` 下并打开拉取请求。
- **在 Python 版本、替代后端（vLLM、llama.cpp、…）或当前未列出的模型上进行了测试？** 让我知道 — 我希望保持与模型无关/版本无关的声明诚实。
## 构建工具
- [uv](https://github.com/astral-sh/uv) — 依赖项管理和锁定文件
- [Ollama](https://ollama.com) — 本地 LLM 推理（默认：`gemma4:e2b`）
- [mem0](https://github.com/mem0ai/mem0) — 长期内存层
- [Qdrant](https://qdrant.tech) — 磁盘矢量存储（嵌入模式）
- [Streamlit](https://streamlit.io) — 聊天界面
- [FastAPI](https://fastapi.tiangolo.com) — OpenAPI 3.0 HTTP 包装器
- [mcp Python SDK / FastMCP](https://github.com/modelcontextprotocol/python-sdk) — 标准的模型上下文协议服务器
- [tox](https://tox.wiki) / [nox](https://nox.thea.codes) — 多环境测试编排
## 联系
**Tiago Monteiro**
- 电子邮件：monteiro.t@northeastern.edu
- GitHub：[@tiagomonteiro0715](https://github.com/tiagomonteiro0715)
- FreeCodeCamp：[作者简介](https://www.freecodecamp.org/news/author/tiagomonteiro)
## 许可证
Apache License 2.0. 见 [LICENSE](LICENSE).
<p align="center">
如果此模板帮助您交付本地代理堆栈，请给存储库加星。<br>
它帮助其他人找到它。
</p>
