RLAMA - 用户指南

⚠️ 项目暂时暂停
由于我的工作和大学事务占据了大量时间，该项目目前处于暂停状态。我暂时无法积极维护此项目。待情况允许时，开发将重新启动。

RLAMA 是一款功能强大的 AI 驱动文档问答工具，可无缝集成到您本地的 Ollama 模型中。它使您能够创建、管理和交互基于检索增强生成（RAG）的系统，以满足您的文档需求。

目录

• 愿景与路线图
• 安装
• 可用命令
  • rag - 创建 RAG 系统
  • crawl-rag - 从网站创建 RAG 系统
  • wizard - 使用交互式设置创建 RAG 系统
  • watch - 为 RAG 系统设置目录监控
  • watch-off - 停用 RAG 系统的目录监控
  • check-watched - 检查 RAG 的监控目录是否有新文件
  • web-watch - 为 RAG 系统设置网站监控
  • web-watch-off - 停用 RAG 系统的网站监控
  • check-web-watched - 检查 RAG 监控的网站是否有更新
  • run - 使用 RAG 系统
  • api - 启动 API 服务器
  • list - 列出 RAG 系统
  • delete - 删除 RAG 系统
  • list-docs - 列出 RAG 中的文档
  • list-chunks - 检查文档分块
  • view-chunk - 查看分块详情
  • add-docs - 向 RAG 添加文档
  • crawl-add-docs - 向 RAG 添加网站内容
  • update-model - 更改 LLM 模型
  • update - 更新 RLAMA
  • version - 显示版本信息
  • hf-browse - 浏览 Hugging Face 上的 GGUF 模型
  • run-hf - 运行 Hugging Face GGUF 模型
• 卸载
• 支持的文档格式
• 故障排除
• 使用 OpenAI 模型

愿景与路线图

RLAMA 致力于成为创建本地 RAG 系统的权威工具，让每个人都能无缝使用——无论是个人开发者还是大型企业。以下是我们的战略路线图：

已完成的功能 ✅

• ✅ 基础 RAG 系统创建：用于创建和管理 RAG 系统的 CLI 工具
• ✅ 文档处理：支持多种文档格式（.txt、.md、.pdf 等）
• ✅ 文档分块：采用多种策略进行高级语义分块（固定大小、语义、层次化、混合）
• ✅ 向量存储：本地存储文档嵌入
• ✅ 上下文检索：基本的语义搜索，可配置上下文大小
• ✅ Ollama 集成：与 Ollama 模型无缝连接
• ✅ 跨平台支持：适用于 Linux、macOS 和 Windows
• ✅ 简易安装：一行安装脚本
• ✅ API 服务器：HTTP 端点，用于在其他应用程序中集成 RAG 功能
• ✅ 网页爬取：直接从网站创建 RAG
• ✅ 引导式 RAG 设置向导：交互式界面，方便轻松创建 RAG
• ✅ Hugging Face 集成：可访问 Hugging Face Hub 上的 45,000 多个 GGUF 模型

小型 LLM 优化（2025 年第二季度）

• 提示压缩：针对有限上下文窗口的智能上下文摘要
• ✅ 自适应分块：根据语义边界和文档结构动态分割内容
• ✅ 最小化上下文检索：智能过滤冗余内容
• 参数优化：针对不同模型规模的精细调优设置

高级嵌入流水线（2025 年第二至第三季度）

• 多模型嵌入支持：集成多种嵌入模型
• 混合检索技术：结合稀疏和密集检索器以提高准确性
• 嵌入评估工具：内置指标用于衡量检索质量
• 自动嵌入缓存：智能缓存机制，减少相似查询的计算量

用户体验提升（2025 年第三季度）

• 轻量级 Web 界面：基于现有 CLI 后端的简单浏览器界面
• 知识图可视化：交互式探索文档之间的关联
• 领域特定模板：针对不同领域的预配置设置

企业级功能（2025 年第四季度）

• 多用户访问控制：面向团队环境的角色权限管理
• 与企业系统集成：SharePoint、Confluence、Google Workspace 等的连接器
• 知识质量监控：检测过时或相互矛盾的信息
• 系统集成 API：用于将 RLAMA 嵌入现有工作流程的 Webhook 和 API
• AI 代理创建框架：简化构建具备 RAG 能力的自定义 AI 代理的系统

下一代检索创新（2026年第一季度）

• 多步检索：利用大语言模型对复杂问题的搜索查询进行优化
• 跨模态检索：支持图像内容的理解与检索
• 基于反馈的优化：通过用户交互学习来改进检索效果
• 知识图谱与符号推理：将向量检索与结构化知识相结合

RLAMA 的核心理念始终不变：提供一个简单、强大且本地化的 RAG 解决方案，既尊重隐私、又最大限度地降低资源需求，并能在跨平台环境中无缝运行。

安装

先决条件

• 已安装并运行 Ollama (https://ollama.ai/)

通过终端安装

curl -fsSL https://raw.githubusercontent.com/dontizi/rlama/main/install.sh | sh

技术栈

RLAMA 采用以下技术构建：

• 核心语言：Go（因其性能、跨平台兼容性以及单二进制分发而被选用）
• CLI 框架：Cobra（用于命令行界面的结构设计）
• LLM 集成：Ollama API（用于嵌入和补全）
• 存储：基于本地文件系统的存储（使用 JSON 文件以简化和便于移植）
• 向量检索：自定义实现的余弦相似度算法，用于嵌入检索

架构

RLAMA 遵循清晰的架构模式，实现了明确的关注点分离：

rlama/
├── cmd/                  # CLI 命令（使用 Cobra）
│   ├── root.go           # 基础命令
│   ├── rag.go            # 创建 RAG 系统
│   ├── run.go            # 查询 RAG 系统
│   └── ...
├── internal/
│   ├── client/           # 外部 API 客户端
│   │   └── ollama_client.go # Ollama API 集成
│   ├── domain/           # 核心领域模型
│   │   ├── rag.go        # RAG 系统实体
│   │   └── document.go   # 文档实体
│   ├── repository/       # 数据持久化
│   │   └── rag_repository.go # 负责保存和加载 RAG
│   └── service/          # 业务逻辑
│       ├── rag_service.go      # RAG 操作
│       ├── document_loader.go  # 文档处理
│       └── embedding_service.go # 向量嵌入
└── pkg/                  # 共享工具
    └── vector/           # 向量运算

数据流

1. 文档处理：从文件系统加载文档，根据其类型进行解析，并转换为纯文本。
2. 嵌入生成：将文档文本发送至 Ollama 以生成向量嵌入。
3. 存储：RAG 系统（文档 + 嵌入）存储在用户的主目录下 (~/.rlama)。
4. 查询过程：当用户提出问题时，将其转换为嵌入，与存储的文档嵌入进行比较，并检索相关内容。
5. 响应生成：将检索到的内容和问题一起发送至 Ollama，以生成上下文相关的回答。

可视化表示

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Documents  │────>│  Document   │────>│  Embedding  │
│  (Input)    │     │  Processing │     │  Generation │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Query     │────>│  Vector     │<────│ Vector Store│
│  Response   │     │  Search     │     │ (RAG System)│
└─────────────┘     └─────────────┘     └─────────────┘
       ▲                   │
       │                   ▼
┌─────────────┐     ┌─────────────┐
│   Ollama    │<────│   Context   │
│    LLM      │     │  Building   │
└─────────────┘     └─────────────┘

RLAMA 的设计注重轻量化和便携性，旨在以最少的依赖项提供 RAG 功能。整个系统在本地运行，唯一的外部依赖是用于 LLM 功能的 Ollama。

可用命令

您可以通过以下命令获取所有命令的帮助信息：

rlama --help

全局选项

这些选项可与任何命令一起使用：

--host string       Ollama 主机地址（默认：localhost）
--port string       Ollama 端口（默认：11434）
--num-thread int    Ollama 使用的线程数（默认：0，使用 Ollama 默认值）

性能优化：

• 使用 --num-thread 16（或您的 CPU 核心数）可以潜在地提高处理速度
• Ollama 默认通常只使用一半可用的核心
• 将此设置为您全部的核心数可以显著加快文本生成和嵌入的速度

使用示例：

# 使用 16 个线程以获得更好的性能
rlama --num-thread 16 run my-docs

# 创建一个优化线程使用的 RAG
rlama --num-thread 16 rag llama3 documentation ./docs

# 使用自定义主机和线程设置运行
rlama --host 192.168.1.100 --port 11434 --num-thread 16 run my-rag

自定义数据目录

RLAMA 默认将数据存储在 ~/.rlama 中。如需使用其他位置：

1. 命令行标志（优先级最高）：

   # 与任何命令一起使用
   rlama --data-dir /path/to/custom/directory run my-rag
   

2. 环境变量：

   # 设置环境变量
   export RLAMA_DATA_DIR=/path/to/custom/directory
   rlama run my-rag
   

优先级顺序为：命令行标志 > 环境变量 > 默认位置。

rag - 创建 RAG 系统

通过索引指定文件夹中的所有文档来创建一个新的 RAG 系统。

rlama rag [model] [rag-name] [folder-path]

参数：

• model：要使用的 Ollama 模型名称（例如 llama3、mistral、gemma），或使用 hf.co/用户名/仓库[:量化] 格式的 Hugging Face 模型。
• rag-name：用于标识您的 RAG 系统的唯一名称。
• folder-path：包含您文档的文件夹路径。

示例：

# 使用标准 Ollama 模型
rlama rag llama3 documentation ./docs

# 使用 Hugging Face 模型
rlama rag hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF my-rag ./docs

# 使用带有特定量化设置的 Hugging Face 模型
rlama rag hf.co/mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF:Q5_K_M my-rag ./docs

crawl-rag - 从网站创建 RAG 系统

通过抓取网站并对其内容建立索引，创建一个新的 RAG 系统。

rlama crawl-rag [模型] [rag-名称] [网站-URL]

参数：

• 模型: 要使用的 Ollama 模型名称（例如，llama3、mistral、gemma）。
• rag-名称: 用于标识您的 RAG 系统的唯一名称。
• 网站-URL: 要抓取和索引的网站 URL。

选项：

• --max-depth: 最大抓取深度（默认：2）
• --concurrency: 并发爬虫数量（默认：5）
• --exclude-path: 需要排除的路径（逗号分隔）
• --chunk-size: 每个块的字符数（默认：1000）
• --chunk-overlap: 块之间的重叠字符数（默认：200）
• --chunking-strategy: 使用的分块策略（选项：“fixed”、“semantic”、“hybrid”、“hierarchical”，默认：“hybrid”）

分块策略

RLAMA 提供多种高级分块策略，以优化文档检索：

• Fixed: 传统的固定大小和重叠分块方式，尽可能尊重句子边界。
• Semantic: 根据语义边界（如标题、段落和自然的主题转换）智能地拆分文档。
• Hybrid: 自动根据文档类型和内容选择最佳策略（Markdown、HTML、代码或纯文本）。
• Hierarchical: 对于非常长的文档，创建包含主要章节和子块的两级分块结构。

系统会自动适应不同的文档类型：

• Markdown 文档：按标题和章节拆分
• HTML 文档：按语义 HTML 元素拆分
• 代码文档：按函数、类和逻辑块拆分
• 纯文本：按段落拆分，并保留上下文重叠。

示例：

# 从文档网站创建新的 RAG
rlama crawl-rag llama3 docs-rag https://docs.example.com

# 自定义抓取行为
rlama crawl-rag llama3 blog-rag https://blog.example.com --max-depth=3 --exclude-path=/archive,/tags

# 使用语义分块创建 RAG
rlama rag llama3 documentation ./docs --chunking-strategy=semantic

# 对于大型文档使用分层分块
rlama rag llama3 book-rag ./books --chunking-strategy=hierarchical

wizard - 通过交互式设置创建 RAG 系统

提供一个交互式的逐步向导，用于创建新的 RAG 系统。

rlama wizard

向导将引导您完成以下步骤：

• 为您的 RAG 命名
• 选择 Ollama 模型
• 选择文档来源（本地文件夹或网站）
• 配置分块参数
• 设置文件过滤

示例：

rlama wizard
# 按照提示创建您自定义的 RAG

watch - 为 RAG 系统设置目录监控

配置 RAG 系统，使其自动监视指定目录中的新文件，并将其添加到 RAG 中。

rlama watch [rag-名称] [目录-路径] [间隔]

参数：

• rag-名称: 要监视的 RAG 系统名称。
• 目录-路径: 要监视新文件的目录路径。
• 间隔: 检查新文件的时间间隔（以分钟为单位；使用 0 表示仅在 RAG 被使用时检查）。

示例：

# 设置每 60 分钟检查一次的目录监控
rlama watch my-docs ./watched-folder 60

# 设置仅在 RAG 被使用时检查的目录监控
rlama watch my-docs ./watched-folder 0

# 自定义要监视的文件
rlama watch my-docs ./watched-folder 30 --exclude-dir=node_modules,tmp --process-ext=.md,.txt

watch-off - 关闭 RAG 系统的目录监控

关闭 RAG 系统的自动目录监控功能。

rlama watch-off [rag-名称]

参数：

• rag-名称: 要停止监控的 RAG 系统名称。

示例：

rlama watch-off my-docs

check-watched - 检查 RAG 的监视目录中是否有新文件

手动检查 RAG 监视的目录中是否有新文件，并将其添加到 RAG 中。

rlama check-watched [rag-名称]

参数：

• rag-名称: 要检查的 RAG 系统名称。

示例：

rlama check-watched my-docs

web-watch - 为 RAG 系统设置网站监控

配置 RAG 系统，使其自动监控网站更新，并将新内容添加到 RAG 中。

rlama web-watch [rag-名称] [网站-URL] [间隔]

参数：

• rag-名称: 要监控的 RAG 系统名称。
• 网站-URL: 要监控的网站 URL。
• 间隔: 检查之间的时间间隔（以分钟为单位；使用 0 表示仅在 RAG 被使用时检查）。

示例：

# 设置每 60 分钟检查一次的网站监控
rlama web-watch my-docs https://example.com 60

# 设置仅在 RAG 被使用时检查的网站监控
rlama web-watch my-docs https://example.com 0

# 自定义要监控的内容
rlama web-watch my-docs https://example.com 30 --exclude-path=/archive,/tags

web-watch-off - 关闭 RAG 系统的网站监控

关闭 RAG 系统的自动网站监控功能。

rlama web-watch-off [rag-名称]

参数：

• rag-名称: 要停止监控的 RAG 系统名称。

示例：

rlama web-watch-off my-docs

check-web-watched - 检查 RAG 监控的网站是否有更新

手动检查 RAG 监控的网站是否有新更新，并将其添加到 RAG 中。

rlama check-web-watched [rag-名称]

参数：

• rag-名称: 要检查的 RAG 系统名称。

示例：

rlama check-web-watched my-docs

run - 使用 RAG 系统

启动一个交互式会话，与现有的 RAG 系统进行交互。

rlama run [rag-名称]

参数：

• rag-名称: 要使用的 RAG 系统名称。
• --context-size: （可选）要检索的上下文块数量（默认：20）。

示例：

rlama run documentation
> 如何安装该项目？
> 主要功能有哪些？
> exit

上下文大小提示：

• 较小的值（5–15）适合快速响应并获取关键信息。
• 中等值（20–40）可在性能和信息量之间取得平衡。
• 较大的值（50+）适用于需要广泛背景信息的复杂问题。
• 请考虑您的模型的上下文窗口限制。

rlama run documentation --context-size=50  # 使用 50 个上下文块

api - 启动 API 服务器

启动一个 HTTP API 服务器，通过 RESTful 端点暴露 RLAMA 的功能。

rlama api [--port PORT]

参数：

• --port:（可选）API 服务器运行的端口号（默认：11249）

示例：

rlama api --port 8080

可用端点：

1. 查询 RAG 系统 - POST /rag

   curl -X POST http://localhost:11249/rag \
     -H "Content-Type: application/json" \
     -d '{
       "rag_name": "documentation",
       "prompt": "如何安装该项目？",
       "context_size": 20
     }'
   

   请求字段：

   • rag_name（必填）：要查询的 RAG 系统名称
   • prompt（必填）：发送给 RAG 的问题或提示
   • context_size（可选）：包含在上下文中的块数
   • model（可选）：覆盖 RAG 使用的模型

2. 检查服务器健康状态 - GET /health

   curl http://localhost:11249/health
   

集成示例：

// Node.js 示例
const response = await fetch('http://localhost:11249/rag', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    rag_name: 'my-docs',
    prompt: '总结主要特性'
  })
});
const data = await response.json();
console.log(data.response);

list - 列出 RAG 系统

显示所有可用的 RAG 系统列表。

rlama list

delete - 删除 RAG 系统

永久删除一个 RAG 系统及其所有已索引的文档。

rlama delete [rag-name] [--force/-f]

参数：

• rag-name：要删除的 RAG 系统名称。
• --force 或 -f：（可选）无需确认直接删除。

示例：

rlama delete old-project

或者不需确认直接删除：

rlama delete old-project --force

list-docs - 列出 RAG 中的文档

显示 RAG 系统中所有文档及其元数据。

rlama list-docs [rag-name]

参数：

• rag-name：RAG 系统名称

示例：

rlama list-docs documentation

list-chunks - 检查文档块

列出并筛选 RAG 系统中的文档块，提供多种选项：

# 基本块列表
rlama list-chunks [rag-name]

# 显示内容预览（前 100 个字符）
rlama list-chunks [rag-name] --show-content

# 按文档名/ID 子串过滤
rlama list-chunks [rag-name] --document=readme

# 组合选项
rlama list-chunks [rag-name] --document=api --show-content

选项：

• --show-content：显示块内容预览
• --document：按文档名/ID 子串过滤

输出列：

• 块 ID（用于 view-chunk 命令）
• 文档来源
• 块位置（例如，“2/5”表示五个块中的第二个）
• 内容预览（如果启用）
• 创建日期

view-chunk - 查看块详情

显示特定块的详细信息。

rlama view-chunk [rag-name] [chunk-id]

参数：

• rag-name：RAG 系统名称
• chunk-id：来自 list-chunks 的块标识符

示例：

rlama view-chunk documentation doc123_chunk_0

add-docs - 向 RAG 添加文档

将新文档添加到现有 RAG 系统中。

rlama add-docs [rag-name] [folder-path] [flags]

参数：

• rag-name：RAG 系统名称
• folder-path：文档文件夹路径

示例：

rlama add-docs documentation ./new-docs --exclude-ext=.tmp

crawl-add-docs - 将网站内容添加到 RAG

将网站内容添加到现有 RAG 系统中。

rlama crawl-add-docs [rag-name] [website-url]

参数：

• rag-name：RAG 系统名称
• website-url：要抓取并添加到 RAG 的网站 URL

选项：

• --max-depth：最大抓取深度（默认：2）
• --concurrency：并发爬虫数量（默认：5）
• --exclude-path：要排除的路径（逗号分隔）
• --chunk-size：每个块的字符数（默认：1000）
• --chunk-overlap：块之间的重叠字符数（默认：200）

示例：

# 将博客内容添加到现有 RAG
rlama crawl-add-docs my-docs https://blog.example.com

# 自定义抓取行为
rlama crawl-add-docs knowledge-base https://docs.example.com --max-depth=1 --exclude-path=/api

update-model - 更改 LLM 模型

更新 RAG 系统使用的 LLM 模型。

rlama update-model [rag-name] [new-model]

参数：

• rag-name：RAG 系统名称
• new-model：新的 Ollama 模型名称

示例：

rlama update-model documentation deepseek-r1:7b-instruct

update - 更新 RLAMA

检查是否有 RLAMA 的新版本，并进行安装。

rlama update [--force/-f]

选项：

• --force 或 -f：（可选）无需确认直接更新。

version - 显示版本

显示 RLAMA 的当前版本。

rlama --version

或者

rlama -v

hf-browse - 浏览 Hugging Face 上的 GGUF 模型

搜索并浏览 Hugging Face 上可用的 GGUF 模型。

rlama hf-browse [search-term] [flags]

参数：

• search-term：（可选）搜索关键词（如“llama3”、“mistral”）

标志：

• --open：在默认浏览器中打开搜索结果
• --quant：指定量化类型以供推荐（如 Q4_K_M、Q5_K_M）
• --limit：限制结果数量（默认：10）

示例：

# 搜索 GGUF 模型并显示命令行帮助
rlama hf-browse “llama 3”

# 打开浏览器查看搜索结果
rlama hf-browse mistral --open

# 指定量化建议进行搜索
rlama hf-browse phi --quant Q4_K_M

run-hf - 运行 Hugging Face GGUF 模型

使用 Ollama 直接运行 Hugging Face GGUF 模型。这在用其创建 RAG 系统之前测试模型时非常有用。

rlama run-hf [huggingface-model] [flags]

参数：

• huggingface-model：Hugging Face 模型路径，格式为“用户名/仓库”

标志：

• --quant：要使用的量化方式（如 Q4_K_M、Q5_K_M）

示例：

# 以聊天模式试用模型
rlama run-hf bartowski/Llama-3.2-1B-Instruct-GGUF

# 指定量化方式
rlama run-hf mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF --quant Q5_K_M

卸载

卸载 RLAMA：

移除二进制文件

如果您通过 go install 安装：

rlama uninstall

移除数据

RLAMA 的数据存储在 ~/.rlama 中。要移除它：

rm -rf ~/.rlama

支持的文档格式

RLAMA 支持多种文件格式：

• 文本：.txt、.md、.html、.json、.csv、.yaml、.yml、.xml、.org
• 代码：.go、.py、.js、.java、.c、.cpp、.cxx、.h、.rb、.php、.rs、.swift、.kt、.ts、.tsx、.f、.F、.F90、.el、.svelte
• 文档：.pdf、.docx、.doc、.rtf、.odt、.pptx、.ppt、.xlsx、.xls、.epub

建议通过 install_deps.sh 安装依赖项，以提升对某些格式的支持。

故障排除

Ollama 无法访问

如果遇到与 Ollama 的连接错误：

1. 检查 Ollama 是否正在运行。
2. 默认情况下，Ollama 必须可通过 http://localhost:11434 或由 OLLAMA_HOST 环境变量指定的主机和端口访问。
3. 如果您的 Ollama 实例运行在不同的主机或端口上，请使用 --host 和 --port 标志：

   rlama --host 192.168.1.100 --port 8000 list
   rlama --host my-ollama-server --port 11434 run my-rag
   

4. 检查 Ollama 日志以查找潜在错误。

文本提取问题

如果某些格式出现问题：

1. 通过 ./scripts/install_deps.sh 安装依赖项。
2. 确保系统已安装所需工具（如 pdftotext、tesseract 等）。

RAG 未找到相关信息

如果回答不相关：

1. 使用 rlama list 检查文档是否已正确索引。
2. 确保文档内容已正确提取。
3. 尝试更精确地重新表述问题。
4. 考虑在创建 RAG 时调整分块参数。

其他问题

如遇其他问题，请在 GitHub 仓库 上提交问题，并提供以下信息：

1. 执行的确切命令。
2. 命令的完整输出。
3. 操作系统及架构。
4. RLAMA 版本（rlama --version）。

配置 Ollama 连接

RLAMA 提供了多种连接到 Ollama 实例的方式：

1. 命令行标志（优先级最高）：

   rlama --host 192.168.1.100 --port 8080 run my-rag
   

2. 环境变量：

   # 格式：“host:port”或仅“host”
   export OLLAMA_HOST=remote-server:8080
   rlama run my-rag
   

3. 默认值（若未指定其他方法则使用）：

   • 主机：localhost
   • 端口：11434

优先级顺序为：命令行标志 > 环境变量 > 默认值。

高级用法

上下文大小管理

# 以最小上下文快速回答
rlama run my-docs --context-size=10

# 以最大上下文进行深度分析
rlama run my-docs --context-size=50

# 在速度与深度之间取得平衡
rlama run my-docs --context-size=30

带过滤条件的 RAG 创建

rlama rag llama3 my-project ./code \
  --exclude-dir=node_modules,dist \
  --process-ext=.go,.ts \
  --exclude-ext=.spec.ts

分块检查

# 列出分块并预览内容
rlama list-chunks my-project --show-content

# 筛选特定文档的分块
rlama list-chunks my-project --document=architecture

帮助系统

获取完整命令帮助：

rlama --help

特定命令帮助：

rlama rag --help
rlama list-chunks --help
rlama update-model --help

所有命令均支持全局 --host 和 --port 标志，用于自定义 Ollama 连接。

优先级顺序为：命令行标志 > 环境变量 > 默认值。

Hugging Face 集成

RLAMA 现在支持通过 Ollama 的原生集成直接使用来自 Hugging Face 的 GGUF 模型：

浏览 Hugging Face 模型

# 搜索 Hugging Face 上的 GGUF 模型
rlama hf-browse "llama 3"

# 打开浏览器查看搜索结果
rlama hf-browse mistral --open

测试模型

在创建 RAG 之前，您可以直接测试 Hugging Face 模型：

# 以聊天模式尝试模型
rlama run-hf bartowski/Llama-3.2-1B-Instruct-GGUF

# 指定量化方式
rlama run-hf mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF --quant Q5_K_M

使用 Hugging Face 模型创建 RAG

在创建 RAG 系统时可使用 Hugging Face 模型：

# 使用 Hugging Face 模型创建 RAG
rlama rag hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF my-rag ./docs

# 使用特定量化
rlama rag hf.co/mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF:Q5_K_M my-rag ./docs

使用 OpenAI 模型

RLAMA 支持两种方式使用 OpenAI 模型：

方法一：默认 API 密钥（自动使用）

您可以在 Web 界面或通过环境变量设置默认的 OpenAI API 密钥。该密钥将自动用于所有 RLAMA 命令，无需指定配置文件。

通过 Web 界面：

1. 导航至 设置 → 默认 API 密钥
2. 输入您的 OpenAI API 密钥（以 sk- 开头）
3. 单击 保存默认 API 密钥

通过环境变量：

export OPENAI_API_KEY="your-api-key"

使用默认密钥：

# 下列命令将自动使用您的默认 OpenAI API 密钥
rlama rag o3-mini my-rag ./documents
rlama rag gpt-4o another-rag ./docs
rlama update-model my-rag gpt-4o
rlama run my-rag

方法二：命名配置文件（特定使用）

为不同的 OpenAI 账户或组织创建命名配置文件。当需要在不同 API 密钥之间切换时，可使用这些配置文件。

创建配置文件：

# 为不同账户创建配置文件
rlama profile add work-account openai "sk-work-api-key"
rlama profile add personal-account openai "sk-personal-api-key"

使用命名配置文件：

# 使用 --profile 标志指定配置文件
rlama rag o3-mini work-rag ./documents --profile work-account
rlama rag gpt-4o personal-rag ./docs --profile personal-account
rlama update-model my-rag gpt-4o --profile work-account

可用的 OpenAI 模型（2025 年 1 月更新）

推理模型（o 系列）

模型	输入价格	输出价格	上下文长度	描述
o3-mini ⭐	$1.10/1M	$4.40/1M	20 万	最新推理模型，比 o1 便宜 93%
o1-pro	$150.00/1M	$600.00/1M	20 万	功能最强大的推理模型（企业版）
o1	$15.00/1M	$60.00/1M	20 万	高级推理模型

GPT-4 系列

模型	输入价格	输出价格	上下文长度	描述
GPT-4.5 🆕	$75.00/1M	$150.00/1M	12.8 万	自然对话，具备情感智能
GPT-4.1 🆕	$30.00/1M	$60.00/1M	100 万	具有 100 万上下文窗口的最新 GPT-4
GPT-4.1-nano 🆕	$5.00/1M	$15.00/1M	12.8 万	GPT-4.1 的轻量级版本
GPT-4o 🔥	$5.00/1M	$15.00/1M	12.8 万	多模态，支持图像和音频
GPT-4o mini 💰	$0.15/1M	$0.60/1M	12.8 万	GPT-4o 的高效版本

GPT-3.5 系列

模型	输入价格	输出价格	上下文长度	描述
GPT-3.5 Turbo	$0.50/1M	$1.50/1M	1.6 万	快速且经济实惠的模型

图例： ⭐ = 推荐，🆕 = 新增（2025 年），🔥 = 流行，💰 = 经济实惠

成本优化建议：

• 对于重复内容，使用上下文缓存可降低 50% 的成本
• 选择合适的上下文窗口大小
• 针对特定用例测试多种模型
• 在推理任务中考虑使用 o3-mini 以降低成本

注意：仅推理调用 OpenAI API。文档嵌入仍使用 Ollama 进行处理。

管理 API 配置文件

使用默认密钥（大多数用户推荐）

对于大多数用户来说，设置默认 API 密钥是最简单的方法：

通过 Web 界面：

1. 打开 RLAMA Web 界面
2. 转到 设置 → 默认 API 密钥
3. 输入您的 OpenAI API 密钥
4. 保存配置

命令将自动使用您的默认密钥：

# 无需 --profile 参数 - 自动使用默认密钥
rlama rag o3-mini my-rag ./documents
rlama update-model my-rag gpt-4o
rlama run my-rag

使用命名配置文件（高级用户）

适用于管理多个 OpenAI 账户或组织的用户：

创建命名配置文件

通过 CLI：

# 为不同环境创建配置文件
rlama profile add work-openai openai "sk-work-key..."
rlama profile add personal-openai openai "sk-personal-key..."

通过 Web 界面：

1. 导航到 设置 → 命名配置文件
2. 点击 “新建配置文件”
3. 填写配置文件详细信息：
   • 名称：唯一标识符（例如 work-account、personal-account）
   • 提供商：OpenAI（自动选择）
   • API 密钥：您的 OpenAI API 密钥（以 sk- 开头）
   • 描述：配置文件的可选描述

管理配置文件

# 列出所有配置文件
rlama profile list

# 删除一个配置文件
rlama profile delete old-profile

使用命名配置文件

# 使用 --profile 标志指定配置文件
rlama rag gpt-4o work-rag ./documents --profile work-openai
rlama rag o3-mini personal-rag ./documents --profile personal-openai

# 使用特定配置文件更新模型
rlama update-model work-rag gpt-4o --profile work-openai
rlama update-model personal-rag o3-mini --profile personal-openai

Web 界面功能

RLAMA Web 界面提供：

• 实时验证 API 密钥格式
• 安全存储，密钥显示为掩码形式
• 集成示例 显示精确的 CLI 命令
• 模型定价表，包含最新的 2025 年费率
• 使用指南，适用于默认密钥和命名配置文件

各种方法的优势

默认 API 密钥：

• ✅ 设置简单 - 一次配置，处处可用
• ✅ 无需记住配置文件名称
• ✅ 所有命令自动使用
• ✅ 非常适合单个 OpenAI 账户用户

命名配置文件：

• ✅ 可管理多个 API 密钥
• ✅ 支持项目特定配置
• ✅ 实现环境分离（开发/预发布/生产）
• ✅ 方便切换组织账户
• ✅ 提供使用跟踪审计线索

示例工作流程

简单工作流程（默认密钥）

# 1. 在 Web 界面设置默认 API 密钥（一次性设置）
# 2. 直接使用 RLAMA 命令 - 无需配置文件
rlama rag o3-mini my-docs ./docs
rlama run my-docs   # 自动使用默认密钥

高级工作流程（命名配置文件）

# 1. 为不同环境创建配置文件
rlama profile add dev-openai openai "sk-dev-key..."
rlama profile add prod-openai openai "sk-prod-key..."

# 2. 使用特定配置文件创建 RAG
rlama rag o3-mini dev-docs ./dev-docs --profile dev-openai
rlama rag gpt-4o prod-docs ./prod-docs --profile prod-openai

# 3. 使用与各自配置文件关联的 RAG
rlama run dev-docs   # 必须指定配置文件或使用默认
rlama run prod-docs  # 配置文件会为每个 RAG 记住

这种双重方法确保 RLAMA 既能无缝适用于简单的单账户使用场景，也能满足复杂的多账户企业级需求。

RLAMA 快速上手指南

RLAMA 是一款强大的本地 AI 问答工具，专为文档检索增强生成（RAG）设计。它能无缝集成本地 Ollama 模型，帮助你基于个人文档构建私有的知识库问答系统。

⚠️ 项目状态提示
目前该项目因作者工作学业原因暂时暂停维护，但现有功能仍可正常使用。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统：支持 Linux、macOS 和 Windows。
• 核心依赖：必须安装并运行 Ollama。
  • 安装 Ollama 后，请确保至少拉取了一个大语言模型（例如 llama3 或 qwen2），用于处理嵌入和生成回答。
  • 验证安装：在终端运行 ollama list 确认模型已就绪。

安装步骤

RLAMA 提供了一键安装脚本，无需手动编译。

1. 执行安装命令

在终端中运行以下命令（国内用户若下载缓慢，可尝试配置代理或使用镜像加速）：

curl -fsSL https://raw.githubusercontent.com/dontizi/rlama/main/install.sh | sh

2. 验证安装

安装完成后，输入以下命令查看帮助信息，确认安装成功：

rlama --help

基本使用

以下是构建一个本地文档问答系统的最简流程。

第一步：创建 RAG 系统

使用 rag 命令创建一个知识库。该命令会读取指定文件夹下的所有文档（支持 .txt, .md, .pdf 等），利用 Ollama 生成向量嵌入并存储。

命令格式：

rlama rag <模型名称> <知识库名称> <文档文件夹路径>

示例： 假设你有一个名为 my-docs 的文件夹存放技术文档，想使用 llama3 模型构建名为 tech-kb 的知识库：

rlama rag llama3 tech-kb ./my-docs

性能优化提示：如果你的 CPU 核心数较多，可以通过 --num-thread 参数加速处理过程（例如设置为 16）：

rlama --num-thread 16 rag llama3 tech-kb ./my-docs

第二步：与知识库对话

创建完成后，使用 run 命令即可针对该知识库进行提问。

命令格式：

rlama run <知识库名称>

示例： 启动交互式对话：

rlama run tech-kb

进入交互模式后，直接输入你的问题（例如：“如何配置环境变量？”），RLAMA 将检索相关文档片段并结合 Ollama 模型生成准确的回答。

其他常用操作

• 列出所有知识库：

  rlama list
  

• 向现有知识库添加新文档：

  rlama add-docs tech-kb ./new-docs
  

• 删除知识库：

  rlama delete tech-kb
  

---

注：默认数据存储在 ~/.rlama 目录。如需自定义存储路径，可使用 --data-dir 标志或设置 RLAMA_DATA_DIR 环境变量。