plastic-labs/honcho

 [](https://pypi.org/project/honcho-ai/) [](https://npmjs.org/package/@honcho-ai/sdk) [](https://discord.gg/plasticlabs) Honcho 是一个开源记忆库，提供托管服务，用于构建有状态的 agent。它可以与任何模型、框架或架构配合使用。它使 agent 能够构建和维护关于任何实体（用户、agent、群组、想法等）的状态。因为这是一个持续学习的系统，它能够理解随时间变化的实体。使用 Honcho 作为您的记忆系统将使您的 agent 获得更高的留存率、更多的信任，并帮助您建立数据护城河以胜过现有竞争对手。 ## TL;DR - 入门指南 使用 Honcho，您可以轻松设置应用程序的工作流，保存您的交互历史，并利用其推理结果来指导您的 agent 的行为 1. 安装 SDK ``` # Python pip install honcho-ai uv add honcho-ai poetry add honcho-ai ``` 2. 设置您的 `Workspace`、`Peers`、`Session` 并发送 `Messages` ``` from honcho import Honcho # 1. 初始化您的 Honcho 客户端 honcho = Honcho(workspace_id="my-app-testing") # 2. 初始化 Peers alice = honcho.peer("alice") tutor = honcho.peer("tutor") # 3. 创建 Session 并添加 Messages session = honcho.session("session-1") # 从 Peer 添加 Messages 会自动将其添加到 Session 中 session.add_messages( [ alice.message("Hey there — can you help me with my math homework?"), tutor.message("Absolutely. Send me your first problem!"), ] ) ``` 3. 利用 Honcho 的推理结果来指导您的 agent 的行为 ``` ### 1. 使用 Chat Endpoint 以自然语言询问有关您用户的问题 response = alice.chat("What learning styles does the user respond to best?") ### 2. 使用 Session Context 继续与 LLM 的对话 context = session.context(summary=True, tokens=10_000) # 转换为发送到 OpenAI 的格式并获取下一条 Message openai_messages = context.to_openai(assistant=tutor) from openai import OpenAI client = OpenAI() response = client.chat.completions.create( model="gpt-4", messages=openai_messages ) ### 3. 搜索相似的 Messages results = alice.search("Math Homework") ### 4. 获取 Peer 的 Session-scoped Representation alice_representation = session.representation(alice) ``` 这是一个简单的示例，展示了如何使用 Honcho 构建聊天机器人并利用洞察来个性化 agent 的行为。 在 [app.honcho.dev](https://app.honcho.dev) 注册以开始使用 Honcho 的托管版本。 在我们的 [developer docs](https://docs.honcho.dev) 中了解更多使用 Honcho 的方法。 在我们的 [blog](https://blog.plasticlabs.ai/) 上阅读关于该项目的设计理念和历史的文章。 ## 项目结构 - [Usage](#usage) - [Local Development](#local-development) - [Prerequisites and Dependencies](#prerequisites-and-dependencies) - [Setup](#setup) - [Docker](#docker) - [Deploy on Fly](#deploy-on-fly) - [Configuration](#configuration) - [Using config.toml](#using-configtoml) - [Using Environment Variables](#using-environment-variables) - [Configuration Priority](#configuration-priority) - [Example](#example) - [Architecture](#architecture) - [Storage](#storage) - [Reasoning](#reasoning) - [Retrieving Data & Insights](#retrieving-data--insights) - [Contributing](#contributing) - [License](#license) Honcho 项目分为多个仓库，此处托管的是核心服务逻辑。它作为 FastAPI 服务器/API 实现，用于存储有关应用程序状态的数据。 在 `sdks/` 目录中还实现了客户端 SDK，支持 Python 和 TypeScript。 - [Python](https://pypi.org/project/honcho-ai/) - [TypeScript](https://www.npmjs.com/package/@honcho-ai/sdk) 有关如何使用 SDK 的示例位于每个 SDK 文件夹内以及 [SDK Reference](https://docs.honcho.dev/v3/documentation/tutorial/SDK) 中。 文档的 [API Reference](https://docs.honcho.dev/api-reference/introduction) 部分也提供了有关如何使用核心 SDK 的详细示例。 ## 用法 在 [https://app.honcho.dev](https://app.honcho.dev) 注册账户并获取 $100 的免费额度以开始使用。注册后，系统会提示您加入一个组织，该组织将拥有一个 Honcho 的专用实例。 配置 API 密钥并将您的基础 URL 更改为指向 [https://api.honcho.dev](https://api.honcho.dev) 此外，Honcho 可以自托管用于测试和评估目的。有关如何设置 Honcho 本地版本的详细信息，请参阅下方的 [Local Development](#local-development) 部分。 ## 本地开发 以下是设置用于运行 Honcho Server 的本地环境的指南。 ### 前提条件和依赖项 Honcho 使用 [python](https://www.python.org/) 和 [uv](https://docs.astral.sh/uv/) 开发。 最低 python 版本为 `3.9` 最低 uv 版本为 `0.4.9` ### 设置 在系统上安装依赖项后，运行以下步骤以设置本地项目。 1. **克隆仓库** ``` git clone https://github.com/plastic-labs/honcho.git ``` 2. **进入仓库并安装 python 依赖** 我们建议使用虚拟环境将 Honcho 的依赖与同一系统上的其他项目隔离。当您在项目中同步依赖时，`uv` 将创建一个虚拟环境。 ``` cd honcho uv sync ``` 这将创建一个虚拟环境并安装 Honcho 的依赖。默认虚拟环境将位于 `honcho/.venv`。通过以下方式激活虚拟环境： ``` source honcho/.venv/bin/activate ``` 3. **设置数据库** Honcho 利用 [Postgres](https://www.postgresql.org/) 及 pgvector 作为其数据库。开始使用 postgres 数据库的一个简单方法是使用 [Supabase](https://supabase.com/) 创建一个项目 或者，我们提供了一个带有示例数据库配置的 `docker-compose` 模板。 要使用 Docker： ``` cp docker-compose.yml.example docker-compose.yml docker compose up -d database ``` 4. **编辑环境变量** Honcho 使用 `.env` 文件来管理运行时环境变量。为了方便起见，包含了一个 `.env.template` 文件。其中一些配置不是必需的，仅用于额外的日志记录、监控和安全。 以下是必需的配置： ``` DB_CONNECTION_URI= # Connection uri for a postgres database (with postgresql+psycopg prefix) # LLM Provider API Keys（根据您的配置至少需要一个） LLM_ANTHROPIC_API_KEY= # API Key for Anthropic (used for dialectic by default) LLM_OPENAI_API_KEY= # API Key for OpenAI (optional, for embeddings if EMBED_MESSAGES=true) LLM_GEMINI_API_KEY= # API Key for Google Gemini (used for summary/deriver by default) LLM_GROQ_API_KEY= # API Key for Groq (used for query generation by default) ``` 模板默认禁用了附加功能。为确保它们被禁用，您可以验证以下环境变量是否设置为 false： ``` AUTH_USE_AUTH=false SENTRY_ENABLED=false ``` 如果您将 `AUTH_USE_AUTH` 设置为 true，您将需要生成一个 JWT secret。您可以使用以下命令执行此操作： ``` python scripts/generate_jwt_secret.py ``` 这将生成一个 JWT secret 并将其打印到控制台。然后您可以设置 `AUTH_JWT_SECRET` 环境变量。这是 `AUTH_USE_AUTH` 所必需的： ``` AUTH_JWT_SECRET= ``` 5. **运行数据库迁移** 设置好数据库并配置了环境变量后，运行迁移以创建必要的表： ``` uv run alembic upgrade head ``` 这将创建 Honcho 的所有表，包括 workspaces、peers、sessions、messages 和队列系统。 6. **启动 Honcho** 一切设置完成后，您现在可以启动 Honcho 的本地实例。除了数据库之外，还需要运行两个组件： **启动 API server：** ``` uv run fastapi dev src/main.py ``` 这是一个开发服务器，会在代码更改时重新加载。 **启动后台 worker (deriver)：** 在单独的终端中，运行： ``` uv run python -m src.deriver ``` deriver 生成 representation、summaries、peer cards 并管理 dreaming 任务。您可以增加 deriver 的数量以提高运行时效率。 ### Pre-commit Hooks Honcho 使用 pre-commit hooks 来确保整个项目的代码质量和一致性。这些 hooks 会在每次提交前自动对您的代码运行检查，包括 linting、格式化、类型检查和安全扫描。 #### 安装 要在您的开发环境中设置 pre-commit hooks： 1. **使用 uv 安装 pre-commit** ``` uv add --dev pre-commit ``` 2. **安装 pre-commit hooks** ``` uv run pre-commit install \ --hook-type pre-commit \ --hook-type commit-msg \ --hook-type pre-push ``` 这将为 `pre-commit`、`commit-msg` 和 `pre-push` 阶段安装 hooks。 #### Hooks 的功能 pre-commit 配置包括： - **Code Quality**：Python linting 和格式化、TypeScript linting (biome) - **Type Checking**：使用 basedpyright 进行静态类型分析 - **Security**：使用 bandit 进行漏洞扫描 - **Documentation**：Markdown linting 和 license header 检查 - **Testing**：Python 和 TypeScript 代码的自动化测试运行 - **File Hygiene**：尾随空格、行尾、文件大小检查 - **Commit Standards**：传统提交消息验证 #### 手动执行 您可以在不进行提交的情况下对所有文件手动运行 hooks： ``` uv run pre-commit run --all-files ``` 或运行特定的 hooks： ``` uv run pre-commit run ruff --all-files uv run pre-commit run basedpyright --all-files ``` ### Docker 如前所述，包含了一个 `docker-compose` 模板用于运行 Honcho。 作为本地运行 Honcho 的替代方案，也可以使用 compose 模板运行它。 docker-compose 模板设置为使用名为 `.env` 的环境文件。 您也可以复制 `.env.template` 并填入适当的值。 在启动服务之前复制模板并更新相应的环境变量： ``` cd honcho cp .env.template .env # 使用 openai key 和其他所需的环境变量更新文件 cp docker-compose.yml.example docker-compose.yml docker compose up ``` ### 部署到 Fly API 也可以部署在 fly.io 上。按照 [Fly.io Docs](https://fly.io/docs/getting-started/) 设置您的环境和 `flyctl`。 为了方便起见，包含了一个示例 `fly.toml`。 一旦设置好 `flyctl`，使用以下命令启动应用程序： ``` cd honcho flyctl launch --no-deploy # Follow the prompts and edit as you see fit cat .env | flyctl secrets import # Load in your secrets flyctl deploy # Deploy with appropriate environment variables ``` ## 配置 Honcho 使用灵活的配置系统，支持 TOML 文件和环境变量。配置值按以下优先顺序加载（从高到低）： 1. 环境变量 2. `.env` 文件（用于本地开发） 3. `config.toml` 文件 4. 默认值 ### 使用 config.toml 复制示例配置文件以开始使用： ``` cp config.toml.example config.toml ``` 然后根据需要修改值。TOML 文件分为以下几个部分： - `[app]` - 应用程序级设置（日志级别、会话限制、嵌入设置、命名空间） - `[db]` - 数据库连接和连接池设置 - `[auth]` - 身份验证配置 - `[cache]` - Redis 缓存配置 - `[llm]` - LLM 提供商 API 密钥和常规设置 - `[deriver]` - 后台 worker 设置和 representation 配置 - `[peer_card]` - Peer card 生成设置 - `[dialectic]` - Dialectic API 配置及各级别推理设置 - `[summary]` - Session 总结设置 - `[dream]` - Dream 处理配置（包括专家模型和 surprisal 设置） - `[webhook]` - Webhook 配置 - `[metrics]` - Prometheus 基于拉取的指标 - `[telemetry]` - 用于分析的 CloudEvents 遥测 - `[vector_store]` - 向量存储配置 - `[sentry]` - 错误跟踪和监控设置 ### 使用环境变量 所有配置值都可以使用环境变量进行覆盖。环境变量名称遵循以下模式： - `{SECTION}_{KEY}` 用于嵌套设置 - 仅 `{KEY}` 用于应用程序级设置 示例： - `DB_CONNECTION_URI` - 数据库连接字符串 - `AUTH_JWT_SECRET` - JWT 密钥 - `DIALECTIC_LEVELS__low__MODEL` - 低推理级别的模型 - `DERIVER_PROVIDER` - 后台 deriver 的提供商 - `SUMMARY_PROVIDER` - Summary 生成的提供商 - `LOG_LEVEL` - 应用程序日志级别 - `METRICS_ENABLED` - 启用 Prometheus 指标 - `TELEMETRY_ENABLED` - 启用 CloudEvents 遥测 ### 配置优先级 当在多个地方设置了配置值时，Honcho 使用以下优先级： 1. **环境变量** - 始终优先 2. **.env 文件** - 为本地开发加载 3. **config.toml** - 基础配置 4. **默认值** - 内置默认值 这允许您： - 使用 `config.toml` 进行基础配置 - 在生产环境中使用环境变量覆盖特定值 - 使用 `.env` 文件进行本地开发，而无需修改 config.toml ### 示例 如果您在 `config.toml` 中有以下内容： ``` [db] CONNECTION_URI = "postgresql://localhost/honcho_dev" POOL_SIZE = 10 ``` 您可以在生产环境中仅覆盖连接 URI： ``` export DB_CONNECTION_URI="postgresql://prod-server/honcho_prod" ``` 应用程序将使用生产环境的连接 URI，同时保留 config.toml 中的连接池大小。 ## 架构 Honcho 的功能可以分为两个不同的服务：Storage 和 Insights。 ### Peer Paradigm Honcho 使用以实体为中心的模型，其中用户和 agent 都表示为 “[peers](https://blog.plasticlabs.ai/blog/Beyond-the-User-Assistant-Paradigm;-Introducing-Peers)”。这种统一的方法支持： - 混合人类和 AI agent 的多参与者会话 - 可配置的观察设置（哪些 peers 观察哪些其他 peers） - 为所有参与者提供灵活的身份管理 - 支持复杂的多 agent 交互 #### 核心功能 - **Rich Reasoning System**：多种实现方法，从交互中提取结论并构建 peers 的综合 representations - **Chat API**：提供推理感知的响应，将结论与当前上下文整合 - **Background Processing**：用于昂贵的操作（如 representation 更新和会话总结）的异步处理管道 - **Multi-Provider Support**：可针对不同用例配置的 LLM 提供商 ### 存储 Honcho 包含几个不同的原语，用于存储应用程序和 peer 数据。这些数据用于管理对话、建模 peer 身份、构建 RAG 应用程序等。 Honcho 背后的理念是提供一个以 peer 为中心且易于从单用户扩展到百万用户的平台。 以下是不同原语及其关系的映射。 ``` Workspaces ├── Peers ←──────────────────┐ │ ├── Sessions │ │ └── Collections │ │ └── Documents │ │ │ │ │ └── Sessions ←───────────────┤ (many-to-many) ├── Peers ───────────────┘ └── Messages (session-level) ``` **Relationship Details:** - 一个 **Workspace** 包含多个 **Peers** - **Peers** 和 **Sessions** 具有多对多关系（peers 可以参与多个 sessions，sessions 可以有多个 peers） - **Messages** 可以存在于两个级别： - **Session-level**：peers 在 session 内的通信 - **Collections** 属于特定的 **Peers** - **Documents** 存储在 **Collections** 中 熟悉 OpenAI Assistants API 等API 的用户会对这里的许多映射感到熟悉。 #### Workspaces 这是 Honcho 的顶层结构。开发人员可以为不同的 assistants、agents、AI 功能等注册不同的 `Workspaces`。这是一种在用例之间隔离数据并提供多租户功能的方法。 #### Peers 在 `Workspace` 内，一切围绕着 `Peer`。`Peer 对象代表系统中的任何参与者——无论是人类用户还是 AI agents。 这种统一模型支持复杂的多参与者交互。 #### Sessions `Session` 对象代表 `Workspace` 内 `Peers` 之间的一组交互。其他应用程序可能将其称为线程或对话。 Sessions 可以涉及多个 peers，并具有可配置的观察设置。 #### Messages `Message` 代表一个原子数据单元，可以存在于两个级别： - **Session-level Messages**：在 session 上下文中 peers 之间的通信 所有消息都由其源 peer 标记，并且可以异步处理以更新其 representations。这种灵活的设计允许对话交互和更广泛的数据摄取以进行个性建模。 #### Collections 从高层次来看，`Collection` 是一组命名的 `Documents`。熟悉基于 RAG 的应用程序的开发人员会对这些感到熟悉。`Collections` 存储向量嵌入数据，开发人员和 agents 可以使用余弦相似度等函数对其进行检索。 Collections 也由 Honcho 在创建 peers 的 representations 时在内部使用。 #### Documents 如前所述，`Document` 是存储在 `Collection` 中的向量嵌入数据。 ### 推理 Honcho 的推理功能建立在 Storage 服务之上。当为 `Peers` 创建 `Messages` 和 `Sessions` 时，Honcho 将异步推理 peer 心理学以得出有关他们的事实，并将其存储在保留的 `Collections` 中。 管道的高级总结如下： 1. 通过 API 创建 Messages 2. Derivation Tasks 排队等待后台处理，包括： - `representation`：更新 `Peers` 的 representations - `summary`：创建 `Sessions` 的 summaries 3. 基于 Session 的队列处理确保正确的顺序 4. 结果在内部存储 ### 检索数据与洞察 Honcho 提供了几种不同的方法来从系统中检索数据，以最好地满足任何给定应用程序的需求。 #### 获取 Context 在与 LLM 的长时间对话中，context window 会很快填满。为了解决这个问题，Honcho 提供了一个 `context` 端点，它返回 session 中的消息、结论、摘要的组合，直到达到提供的 token 限制。 使用此功能可以无限期地保持 sessions。如果您想看看它的实际效果，请试用 [Honcho Chat](https://honcho.chat)。 #### 搜索 有多个搜索端点允许开发人员使用混合搜索策略在 `Workspace`、`Session` 或 `Peer` 级别查询消息。 请求可以包含高级过滤器以进一步细化结果。 #### Chat API 利用这些洞察的旗舰接口是通过 [`Chat` Endpoint](https://blog.plasticlabs.ai/archive/ARCHIVED;-Introducing-Honcho's-Dialectic-API)。 这是一个常规的 API 端点 (`/peers/{peer_id}/chat`)，接受自然语言请求以获取有关 `Peer` 的数据。这种稳健的设计使我们可以将此单一端点用于所有需要有关 `Peer` 的额外个性化或信息的情况。 开发人员的应用程序可以将 Honcho 视为 `Peer` 的预言机，并在必要时进行咨询。关于如何利用 Dialectic API 的一些示例包括： - 向 Honcho 询问有关 `Peer` 的一般或特定洞察 - 请求 Honcho 用有关 `Peer` 行为的数据填充 prompt - 请求 Honcho 提供关于如何响应 Peer 的第二意见或方法 - 获取结合长期事实和上下文的个性化响应 #### Representations 对于低延迟用例，Honcho 提供对 `representation` 端点的访问，该端点返回一个静态文档，其中包含有关特定 session 上下文中 `Peer` 的洞察。 使用此功能可以快速向 prompt 添加上下文，而无需等待 LLM 响应。 ## 贡献 我们欢迎对 Honcho 的贡献！请阅读我们的 [Contributing Guide](./CONTRIBUTING.md) 以了解有关我们的开发流程、编码约定以及如何提交 pull request 的详细信息。 ## 许可证 Honcho 根据 AGPL-3.0 许可证授权。在 [License file](./LICENSE) 了解更多信息。

标签：DLL 劫持, LLM, NLP, Python SDK, RAG, TypeScript, Unmanaged PE, 上下文管理, 个性化 AI, 人工智能, 分布式搜索, 向量数据库, 大语言模型, 安全插件, 对话系统, 开发框架, 开源, 持续学习, 搜索引擎查询, 有状态代理, 状态管理, 用户模式Hook绕过, 用户画像, 知识存储, 记忆库, 请求拦截, 逆向工具