🇨🇭🎖️🦙 瑞士军刀骆驼

简介

瑞士军刀骆驼旨在通过使用 FastAPI 暴露便捷的 REST API 端点，来简化和优化本地大语言模型（LLM）的工作流程。这些端点支持多种任务，包括利用 llama_cpp 获取不同 LLM 的文本嵌入和补全；同时还能自动处理大多数常见文档类型的嵌入提取，例如 PDF（甚至需要 OCR 处理的文件）、Word 文档等。此外，它还允许用户上传音频文件，自动使用 Whisper 模型进行转录，清理生成的文本，并计算其嵌入向量。为避免重复计算，这些嵌入会被缓存到 SQLite 数据库中，若之前已计算过则直接从缓存中读取。为了加快加载多个 LLM 的速度，还可以选择使用 RAM 盘，而创建和管理 RAM 盘的过程将由系统自动完成。凭借快速简便的部署流程，您将立即获得一个功能强大的“瑞士军刀”式 LLM 工具集，所有功能均可通过便捷的 Swagger UI 访问，并且只需极少的配置即可轻松集成到您自己的应用中。

此外，还提供了一些实用的额外端点，例如计算提交的文本字符串之间的语义相似度。该服务基于高性能的 Rust 库 fast_vector_similarity，支持多种相似度度量方法，包括 Spearman 秩相关系数、Kendall 秩相关系数、近似距离相关性、Jensen-Shannon 相关性度量以及 Hoeffding D 统计量。同时，借助 FAISS 向量检索技术，还支持对所有缓存嵌入进行语义搜索。您可以选择使用 FAISS 内置的余弦相似度，也可以在第一次筛选出最相关的向量后，再进行第二轮更复杂的相似度计算（具体功能请参见高级语义搜索端点）。

另外，我们还支持多种嵌入池化方法，用于将标记级别的嵌入向量组合成固定长度的单个嵌入向量，适用于任意长度的输入文本，包括以下几种：

• mean：标记嵌入的平均池化。
• mins_maxes：将每个维度的最小值和最大值拼接起来。
• svd：将标记嵌入矩阵的奇异值分解得到的前两个奇异向量拼接起来。
• svd_first_four：将标记嵌入矩阵的奇异值分解得到的前四个奇异向量拼接起来。
• ica：对标记嵌入进行独立成分分析后，展开得到的独立成分。
• factor_analysis：对标记嵌入进行因子分析后，展开得到的因子。
• gaussian_random_projection：对标记嵌入进行高斯随机投影后，展开得到的嵌入。

如上所述，现在不仅可以提交纯文本和完全数字化的 PDF 文件，还可以上传 MS Word 文档、图片以及其他由 textract 库支持的文件类型。对于扫描件中的文字，该库会自动使用 Tesseract 进行 OCR 处理。文档中每句话的嵌入向量可以通过 Pandas 的 to_json() 函数以记录、表格等多种格式组织起来。结果可以以包含 JSON 文件的 ZIP 压缩包形式返回，也可以直接以 JSON 格式响应。此外，现在还支持上传 MP3 或 WAV 格式的音频文件。该库使用 OpenAI 的 Whisper 模型，并结合 Faster Whisper Python 库进行优化，将音频转录为文本。用户还可以选择将转录后的文本当作普通文档处理，为其每句话计算并存储嵌入向量。最终结果将以可下载 ZIP 文件的 URL 形式返回，其中包含带有嵌入向量数据的 JSON 文件。

最后，我们新增了一个端点，用于根据给定的提示生成多个文本补全结果，并支持指定语法文件以强制生成特定格式的响应，例如 JSON。此外，还有一个非常实用的新功能：实时应用日志查看器，可通过浏览器访问，支持语法高亮显示，并提供下载日志或复制到剪贴板的选项。这使得用户无需直接 SSH 登录服务器即可实时监控日志。

截图

简要说明： 如果您只想在一台全新的 Ubuntu 22+ 系统上快速试用（注意：此操作会通过 apt 安装 Docker），可以执行以下命令：

git clone https://github.com/Dicklesworthstone/swiss_army_llama
cd swiss_army_llama
chmod +x setup_dockerized_app_on_fresh_machine.sh
sudo ./setup_dockerized_app_on_fresh_machine.sh

如果您希望在 Python 虚拟环境中原生运行（不使用 Docker，推荐方式），可以使用以下命令：

sudo apt-get update
sudo apt-get install build-essential libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig redis-server libpoppler-cpp-dev pkg-config -y
sudo systemctl enable redis-server
sudo systemctl start redis
git clone https://github.com/Dicklesworthstone/swiss_army_llama
cd swiss_army_llama
python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install wheel
python3 -m pip install --upgrade setuptools wheel
pip install -r requirements.txt
python3 swiss_army_llama.py

或者，您也可以直接运行附带的脚本，它会在您的机器上尚未安装 PyEnv 的情况下自动安装 PyEnv，然后安装 Python 3.12 并为您创建虚拟环境。您可以在一台全新的 Ubuntu 机器上仅用一条命令完成所有操作，如下所示：

git clone https://github.com/Dicklesworthstone/swiss_army_llama && cd swiss_army_llama && chmod +x install_swiss_army_llama.sh && ./install_swiss_army_llama.sh && pyenv local 3.12 && source venv/bin/activate && python swiss_army_llama.py

随后，在 VPS 上使用 <your_static_ip_address>:8089 打开浏览器，即可访问 FastAPI 的 Swagger 页面 http://localhost:8089。

如果是在本地机器上运行，则访问 localhost:8089 即可——不过，切记不要在自己的机器上以 sudo 权限运行不受信任的代码！建议租用一台价格低廉的 VPS，每月仅需 30 美元即可进行实验。

您可以在 这里 观看自动化部署过程的实际演示。

---

功能特性

1. 文本嵌入计算：通过 llama_cpp 利用预训练的 LLama3 及其他大语言模型，为任意提供的文本生成嵌入向量。
2. 嵌入缓存：高效地在 SQLite 中存储和检索已计算的嵌入，从而减少重复计算。
3. 高级相似度度量与检索：使用作者自研的 Rust 编写的 fast_vector_similarity 库，提供高度优化的高级相似度度量方法，如 Spearman 秩相关系数、Kendall 等级相关系数、近似距离相关性、Jensen-Shannon 相依性度量及 Hoeffding D 统计量。同时支持基于 FAISS 向量检索技术的缓存嵌入语义搜索。
4. 两步高级语义搜索：API 首先利用 FAISS 和余弦相似度进行快速筛选，随后再应用 Spearman 秩相关系数、Kendall 等级相关系数、近似距离相关性、Jensen-Shannon 相依性度量及 Hoeffding D 等多种相似度度量方法，以实现更为细致的比较。
5. 文档文件处理：该库现可接受更广泛的文件类型，包括纯文本、PDF、MS Word 文档及图像等，并能自动进行 OCR 处理。每句话的嵌入向量将以记录、表格等多种格式返回，使用 Pandas 的 to_json() 函数组织数据。
6. 高级文本预处理：库内采用更先进的句子分割器，将文本切分为有意义的句子。它能够正确处理缩写、域名或数字中出现的句号，并确保即使在引用的情况下也能完整提取句子。此外，还能有效解决扫描文档中常见的分页问题，例如不自然的换行符和连字符断行。
7. 音频转录与嵌入：上传 MP3 或 WAV 格式的音频文件，库会使用 OpenAI 的 Whisper 模型进行转录。用户还可选择为转录文本计算句子嵌入。
8. RAM 盘使用：可选地使用 RAM 盘来存储模型，以加快访问和执行速度。系统会自动创建和管理 RAM 盘。
9. 健壮的异常处理：具备全面的异常处理机制，确保系统的稳定性。
10. 交互式 API 文档：集成 Swagger UI，提供交互友好且用户友好的体验，能够处理大规模结果集而不崩溃。
11. 可扩展性和并发性：基于 FastAPI 框架构建，能够处理并发请求，并支持并行推理，且并发级别可配置。
12. 灵活的配置选项：通过环境变量和输入参数提供可配置设置，包括 JSON 或 ZIP 文件等响应格式。
13. 全面的日志记录：捕获关键信息并生成详细日志，既不会占用过多存储空间，也不会影响日志的可读性。
14. 多模型与多度量支持：兼容多种嵌入模型和相似度度量方法，可根据用户需求灵活定制。
15. 基于指定语法生成多个补全结果：根据给定的输入提示，获取结构化的 LLM 补全结果。
16. 浏览器实时日志查看器：任何有权访问 API 服务器的用户均可方便地查看应用程序日志，从而深入了解其请求的执行过程。
17. 使用 Redis 进行请求锁定：借助 Redis 实现多个 Uvicorn 工作进程的并行运行，避免彼此冲突。

演示屏幕录像

这里是我在 Swagger 页面上与之交互并发出请求时的实时控制台输出。

---

系统要求

运行本应用所需的系统要求（以支持 textract 处理的所有文件类型）：

sudo apt-get update
sudo apt-get install libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig -y

Python 依赖项：

aioredis
aioredlock
aiosqlite
apscheduler
faiss-cpu
fast_vector_similarity
fastapi
faster-whisper
filelock
httpx
llama-cpp-python
magika
mutagen
nvgpu
pandas
pillow
psutil
pydantic
PyPDF2
pytest
python-decouple
python-multipart
pytz
redis
ruff
scikit-learn
scipy
sqlalchemy
textract-py3
uvicorn
uvloop
zstandard

运行应用

您可以通过以下命令运行该应用：

python swiss_army_llama.py

服务器将在 0.0.0.0 上，由 SWISS_ARMY_LLAMA_SERVER_LISTEN_PORT 变量定义的端口启动。

访问 Swagger UI：

http://localhost:<SWISS_ARMY_LLAMA_SERVER_LISTEN_PORT>

配置

您可以通过编辑附带的 .env 文件轻松配置服务。以下是可用的配置选项列表：

• USE_SECURITY_TOKEN：是否使用硬编码的安全令牌。（例如 1）
• USE_PARALLEL_INFERENCE_QUEUE：是否启用并行处理。（例如 1）
• MAX_CONCURRENT_PARALLEL_INFERENCE_TASKS：并行推理任务的最大数量。（例如 30）
• DEFAULT_MODEL_NAME：默认使用的模型名称。（例如 Llama-3-8B-Instruct-64k）
• LLM_CONTEXT_SIZE_IN_TOKENS：LLM 的上下文大小（以 token 数量计）。（例如 512）
• SWISS_ARMY_LLAMA_SERVER_LISTEN_PORT：服务监听的端口号。（例如 8089）
• UVICORN_NUMBER_OF_WORKERS：Uvicorn 的工作进程数量。（例如 2）
• MINIMUM_STRING_LENGTH_FOR_DOCUMENT_EMBEDDING：文档嵌入的最小字符串长度。（例如 15）
• MAX_RETRIES：数据库锁定时的最大重试次数。（例如 10）
• DB_WRITE_BATCH_SIZE：数据库写入批次大小。（例如 25）
• RETRY_DELAY_BASE_SECONDS：每次重试的基础延迟时间（以秒计）。（例如 1）
• JITTER_FACTOR：重试时的抖动因子。（例如 0.1）
• USE_RAMDISK：是否使用 RAM 盘。（例如 1）
• RAMDISK_PATH：RAM 盘的路径。（例如 "/mnt/ramdisk"）
• RAMDISK_SIZE_IN_GB：RAM 盤的大小（以 GB 计）。（例如 40）

贡献

如果您希望为该项目贡献力量，请提交 Pull Request！我非常期待社区的参与，共同将其打造为一个标准库！

许可证

本项目采用 MIT 许可证授权。

我在 Google 上找到的一些羊驼刀图片

---

设置与配置

内存磁盘配置

要为内存磁盘的设置和卸载启用免密码 sudo，请使用 sudo visudo 编辑 sudoers 文件。添加以下行，将 username 替换为您的实际用户名：

username ALL=(ALL) NOPASSWD: /bin/mount -t tmpfs -o size=*G tmpfs /mnt/ramdisk
username ALL=(ALL) NOPASSWD: /bin/umount /mnt/ramdisk

该应用程序提供了设置、清空和管理内存磁盘的功能。内存磁盘用于将模型存储在内存中以实现更快的访问速度。它会计算可用的 RAM 并相应地设置内存磁盘。setup_ramdisk、copy_models_to_ramdisk 和 clear_ramdisk 函数负责管理这些任务。

API 端点

以下是可用的端点：

• GET /get_list_of_available_model_names/：获取可用模型名称。检索可用于生成嵌入的可用模型名称列表。
• GET /get_all_stored_strings/：获取所有字符串。从数据库中检索已计算嵌入的所有存储字符串列表。
• GET /get_all_stored_documents/：获取所有存储文档。从数据库中检索已计算嵌入的所有存储文档列表。
• GET /show_logs/：默认显示最近 5 分钟的日志。也可以通过参数指定，例如 /show_logs/{minutes}，以获取最近 N 分钟的日志数据。
• POST /add_new_model/：通过 URL 添加新模型。提交新模型的下载 URL 并使用。模型必须为 .gguf 格式且大于 100 MB，以确保其为有效模型文件（可以直接粘贴 Hugging Face 的 URL）。
• POST /get_embedding_vector_for_string/：获取给定文本字符串的嵌入向量。使用指定的模型为给定输入文本字符串检索嵌入向量。
• POST /compute_similarity_between_strings/：计算两个字符串之间的相似度。利用 fast_vector_similarity 库，使用指定模型的嵌入和选定的相似度度量来计算两个输入字符串之间的相似度。
• POST /search_stored_embeddings_with_query_string_for_semantic_similarity/：从数据库中存储的嵌入中获取最相似的字符串。查找数据库中与给定“查询”文本最相似的字符串。
• POST /advanced_search_stored_embeddings_with_query_string_for_semantic_similarity/：执行两步高级语义搜索。首先使用 FAISS 和余弦相似度缩小最相似的字符串范围，然后应用其他相似度度量进行更精细的比较。
• POST /get_all_embedding_vectors_for_document/：获取文档的嵌入。提取文档的文本嵌入。该端点支持纯文本、.doc/.docx（MS Word）、PDF 文件、图像（使用 Tesseract OCR）以及 textract 库支持的许多其他文件类型。
• POST /compute_transcript_with_whisper_from_audio/：使用 Whisper 和 LLM 转录并嵌入音频。该端点接受一个音频文件，并可选择同时计算文档嵌入。转录和嵌入会被存储，用户可以下载包含嵌入的 ZIP 文件。
• POST /get_text_completions_from_input_prompt/：从指定的 LLM 模型获取多个补全结果，并可指定一个语法文件，以强制响应采用特定格式，例如 JSON。
• POST /clear_ramdisk/：清空内存磁盘端点。如果启用了内存磁盘，则将其清空。

有关详细的请求和响应模式，请参阅根 URL 或本 README 文档末尾部分提供的 Swagger UI。

异常处理

该应用程序具有强大的异常处理机制，能够应对各种类型的错误，包括数据库错误和一般异常。针对 SQLAlchemyError 和一般 Exception 定义了自定义异常处理器。

日志记录

日志记录配置为 INFO 级别，以便提供详细的调试和监控日志。日志记录器会记录应用程序的状态、错误和活动信息。

日志文件名为 swiss_army_llama.log，并实现了日志文件轮转机制以处理日志备份。轮转文件处理器的最大文件大小设置为 10 MB，最多保留 5 个备份文件。

当日志文件达到最大大小时，它会被移动到 old_logs 目录，并创建一个新的日志文件。日志条目也会输出到标准输出流。

以下是日志配置的一些详细信息：

• 日志级别：INFO
• 日志格式：%(asctime)s - %(levelname)s - %(message)s
• 最大日志文件大小：10 MB
• 备份数量：5
• 旧日志目录：old_logs

此外，SQLAlchemy 引擎的日志级别被设置为 WARNING，以抑制冗长的数据库日志。

数据库结构

该应用程序使用 SQLAlchemy ORM 通过 SQLite 数据库进行操作。以下是使用的数据模型，可在 embeddings_data_models.py 文件中找到：

TextEmbedding 表

• id：主键
• text：已计算嵌入的文本
• text_hash：使用 SHA3-256 计算的文本哈希值
• embedding_pooling_method：用于池化嵌入的方法
• embedding_hash：计算出的嵌入哈希值
• llm_model_name：用于计算嵌入的模型名称
• corpus_identifier_string：用于将嵌入分组到特定语料库的可选字符串标识符
• embedding_json：计算出的嵌入，以 JSON 格式存储
• ip_address：客户端 IP 地址
• request_time：请求时间戳
• response_time：响应时间戳
• total_time：处理请求所花费的总时间
• document_file_hash：引用 DocumentEmbedding 表的外键
• document：与 DocumentEmbedding 的关系

DocumentEmbedding 表

• id：主键
• document_hash：引用 Documents 表的外键
• filename：文档文件名
• mimetype：文档文件的 MIME 类型
• document_file_hash：文件的哈希值
• embedding_pooling_method：用于池化嵌入的方法
• llm_model_name：用于计算嵌入的模型名称
• corpus_identifier_string：用于将文档分组到特定语料库的可选字符串标识符
• file_data：原始文件的二进制数据
• sentences：从文档中提取的句子
• document_embedding_results_json_compressed_binary：使用 Z-standard 压缩算法压缩后的 JSON 格式嵌入结果
• ip_address：客户端 IP 地址
• request_time：请求时间戳
• response_time：响应时间戳
• total_time：处理请求所花费的总时间
• embeddings：与 TextEmbedding 的关系
• document：与 Document 的关系

文档表

• id: 主键
• llm_model_name: 与文档关联的模型名称
• corpus_identifier_string: 可选的字符串标识符，用于将文档分组到特定语料库中
• document_hash: 文档的计算哈希值
• document_embeddings: 与 DocumentEmbedding 的关系

音频转录表

• audio_file_hash: 主键
• audio_file_name: 音频文件名
• audio_file_size_mb: 文件大小（MB）
• segments_json: 转录片段的 JSON 格式
• combined_transcript_text: 合并后的转录文本
• combined_transcript_text_list_of_metadata_dicts: 合并转录中每个片段的元数据字典列表
• info_json: 转录信息的 JSON 格式
• ip_address: 客户端 IP 地址
• request_time: 请求的时间戳
• response_time: 响应的时间戳
• total_time: 处理请求所用的总时间
• corpus_identifier_string: 可选的字符串标识符，用于将转录分组到特定语料库中

数据库关系

1. TextEmbedding - DocumentEmbedding:

   • TextEmbedding 表有一个外键 document_file_hash，引用 DocumentEmbedding 表的 document_file_hash。
   • 这意味着多个文本嵌入可以属于同一个文档嵌入，从而建立了一对多的关系。

2. DocumentEmbedding - Document:

   • DocumentEmbedding 表有一个外键 document_hash，引用 Document 表的 document_hash。
   • 这建立了 Document 和 DocumentEmbedding 之间的一对多关系。

3. AudioTranscript:

   • 根据提供的代码，该表与其他表之间没有直接关系。

4. 请求/响应模型:

   • 这些模型与数据库表没有直接关系，但用于处理 API 请求和响应。
   • 以下 Pydantic 模型用于请求和响应验证：
     • EmbeddingRequest
     • SimilarityRequest
     • SemanticSearchRequest
     • SemanticSearchResponse
     • AdvancedSemanticSearchRequest
     • AdvancedSemanticSearchResponse
     • EmbeddingResponse
     • SimilarityResponse
     • AllStringsResponse
     • AllDocumentsResponse
     • TextCompletionRequest
     • TextCompletionResponse
     • ImageQuestionResponse
     • AudioTranscriptResponse
     • ShowLogsIncrementalModel
     • AddGrammarRequest
     • AddGrammarResponse

有关详细字段说明和验证，请参阅 embeddings_data_models.py 文件。

性能优化

本节重点介绍了集成到所提供代码中的主要性能增强措施，以确保快速响应和最佳资源管理。

1. 异步编程：

• 优势：能够并发处理多项任务，提升 I/O 密集型操作（如数据库事务和网络请求）的效率。
• 实现：使用 Python 的 asyncio 库进行异步数据库操作。

2. 数据库优化：

• 预写日志（WAL）模式：支持并发读写，特别适用于频繁写入的应用场景。
• 指数退避重试逻辑：通过逐步增加等待时间来重试操作，以应对数据库锁定情况。
• 批量写入：将写入操作聚合在一起，提高数据库交互效率。
• 数据库写入队列：使用异步队列序列化写入操作，确保数据库写入的一致性和无冲突性。

3. RAM 盘利用：

• 优势：通过优先在内存中执行 I/O 密集型任务，而不是在磁盘上，从而加快处理速度。
• 实现：检测并优先使用 RAM 盘（/mnt/ramdisk），如果可用；否则默认使用标准文件系统。

4. 模型缓存：

• 优势：通过将加载的模型保留在内存中，减少后续请求的开销。
• 实现：使用全局 model_cache 字典存储和检索模型。

5. 并行推理：

• 优势：提升对多个数据单元（如文档中的句子）的处理速度。
• 实现：采用 asyncio.gather 进行并发推理，并通过信号量（MAX_CONCURRENT_PARALLEL_INFERENCE_TASKS）进行控制。

6. 嵌入缓存：

• 优势：一旦为特定文本计算出嵌入，就会将其存储在数据库中，从而避免在后续请求中重复计算。
• 实现：当收到计算嵌入的请求时，系统会首先检查数据库。如果找到该文本的嵌入，则立即返回，从而确保更快的响应时间。

---

容器化版本

本仓库包含一个 Bash 脚本 setup_dockerized_app_on_fresh_machine.sh，它可以自动为您完成所有操作，包括使用 apt install 安装 Docker。

要使用该脚本，请先将其设置为可执行文件，然后按如下方式运行：

chmod +x setup_dockerized_app_on_fresh_machine.sh
sudo ./setup_dockerized_app_on_fresh_machine.sh

如果您更倾向于手动安装，请阅读以下说明：

先决条件

请确保您的系统上已安装 Docker。如果没有，请按照以下步骤在 Ubuntu 上安装 Docker：

sudo apt-get update
sudo apt-get install docker.io
sudo systemctl start docker
sudo docker --version
sudo usermod -aG docker $USER

您可能需要注销并重新登录，或重启系统以使新的组权限生效；否则，在后续步骤中构建和运行容器时，需使用 sudo。

应用程序的设置与运行

1. 克隆仓库：

   将 Swiss Army Llama 仓库克隆到本地机器：

   git clone https://github.com/Dicklesworthstone/swiss_army_llama
   cd swiss_army_llama
   

2. 构建 Docker 镜像：

   使用提供的 Dockerfile 构建 Docker 镜像：

   sudo docker build -t llama-embeddings .
   

3. 运行 Docker 容器：

   运行 Docker 容器，并将容器的 8089 端口映射到主机的 8089 端口：

   sudo docker run -p 8089:8089 llama-embeddings
   

4. 访问应用程序：

   此时，FastAPI 应用程序可通过 http://localhost:8089 访问，或者如果您在 VPS 实例上运行，则可通过其静态 IP 地址访问（您可以在 Contabo 以约 30 美元/月的价格租用一台配备 10 核 CPU、30GB 内存、1TB SSD 并带有静态 IP 的 Ubuntu 22.04 服务器，这是我目前找到的最便宜的选择）。

   您可以使用 curl 等工具与 API 交互，或通过 http://localhost:8089/docs 访问 FastAPI 文档。

5. 查看日志：

   应用程序的日志可以直接在运行 docker run 命令的终端中查看。

停止与管理容器

• 要停止正在运行的容器，可在终端中按 Ctrl+C，或使用 docker ps 查找容器 ID，然后运行 sudo docker stop <container_id>。
• 若要删除已构建的镜像，可使用 sudo docker rmi llama-embeddings。

---

启动流程

在启动过程中，应用程序会执行以下任务：

1. 数据库初始化：
   • 应用程序会初始化 SQLite 数据库，创建表并执行重要的 PRAGMA 命令以优化性能。
   • 一些重要的 SQLite PRAGMA 包括将数据库设置为预写日志（WAL）模式、同步模式设为 NORMAL、缓存大小增加至 1GB、忙超时时间设为 2 秒，以及 WAL 自动检查点设为 100。
2. 初始化数据库写入器：
   • 会初始化一个专用的数据库写入器 (DatabaseWriter) 和一个异步队列来处理写入操作。
   • 创建一组哈希值，用于记录当前正在处理或已完成的操作，从而避免队列中出现重复操作。
3. RAM 盘设置：
   • 如果启用了 USE_RAMDISK 变量且用户具有相应权限，应用程序将设置 RAM 盘。
   • 应用程序会检查指定路径是否已存在 RAM 盘；如果不存在，则计算最佳 RAM 盘大小并进行设置。
   • 如果启用了 RAM 盘功能但用户缺乏必要权限，RAM 盘功能将被禁用，应用程序将继续运行而不使用 RAM 盘。
4. 模型下载：
   • 应用程序会下载所需的模型。
5. 模型加载：
   • 每个下载的模型都会被加载到内存中。如果发现任何模型文件缺失，则会记录错误日志。
6. 构建 FAISS 索引：
   • 应用程序会基于数据库中的嵌入向量创建 FAISS 索引，以便高效地进行相似度搜索。
   • 相关文本会按模型名称存储，以供后续使用。

注意：

• 如果启用了 RAM 盘功能但用户缺乏必要权限，应用程序将禁用 RAM 盘功能并继续运行。
• 对于任何数据库操作，如果数据库被锁定，应用程序将尝试采用指数退避和抖动机制重试几次。

---

端点功能与工作流程概述

以下是 FastAPI 服务器提供的主要端点的详细说明，包括其功能、输入参数以及它们如何与底层模型和系统交互：

1. /get_embedding_vector_for_string/ (POST)

目的

使用指定模型获取给定文本字符串的嵌入向量。

参数

• text: 要获取嵌入向量的输入文本。
• model_name: 用于计算嵌入的模型名称（可选；未提供时将使用默认模型）。
• token: 安全令牌（可选）。
• client_ip: 客户端 IP 地址（可选）。

流程

1. 获取嵌入：函数会使用指定或默认模型检索或计算所提供文本的嵌入向量。
2. 返回结果：响应中将返回输入文本字符串的嵌入向量。

2. /compute_similarity_between_strings/ (POST)

目的

使用指定模型的嵌入向量和选定的相似度度量方法，计算两个输入字符串之间的相似度。

参数

• text1: 第一个输入文本。
• text2: 第二个输入文本。
• llm_model_name: 用于计算嵌入的模型名称（可选）。
• similarity_measure: 要使用的相似度度量方法。支持的方法包括 all、spearman_rho、kendall_tau、approximate_distance_correlation、jensen_shannon_dependency_measure 和 hoeffding_d（可选；默认为 all）。

流程

1. 获取嵌入：使用指定或默认模型检索或计算 text1 和 text2 的嵌入向量。
2. 计算相似度：根据指定的相似度度量方法计算两个嵌入向量之间的相似度。
3. 返回结果：响应中将返回相似度分数，以及嵌入向量和输入文本。

3. /search_stored_embeddings_with_query_string_for_semantic_similarity/ (POST)

目的

在数据库中查找与给定输入“query”文本最相似的字符串。该端点使用预先计算好的 FAISS 索引，快速搜索最接近的匹配字符串。

参数

• query_text: 用于查找最相似字符串的输入文本。
• model_name: 用于计算嵌入的模型。
• number_of_most_similar_strings_to_return:（可选）返回的最相似字符串数量，默认为 10。
• token: 安全令牌（可选）。

工作流程

1. 搜索 FAISS 索引：通过基于存储嵌入构建的 FAISS 索引，查找与 query_text 最相似的嵌入。
2. 返回结果：将数据库中找到的最相似字符串及其相似度分数返回到响应中。

4. /advanced_search_stored_embeddings_with_query_string_for_semantic_similarity/ (POST)

目的

执行两步高级语义搜索。首先利用 FAISS 和余弦相似度进行初步筛选，随后再使用其他相似度度量进行精细化比较。

参数

• query_text: 用于查找最相似字符串的输入文本。
• llm_model_name: 用于计算嵌入的模型。
• similarity_filter_percentage:（可选）根据余弦相似度筛选的嵌入百分比；默认为 0.02（即前 2%）。
• number_of_most_similar_strings_to_return:（可选）在第二次相似度度量后返回的最相似字符串数量；默认为 10。

工作流程

1. 初始筛选：使用 FAISS 和余弦相似度查找一组相似字符串。
2. 精细化比较：对筛选后的集合应用额外的相似度度量。
3. 返回结果：返回最相似的字符串及其多个相似度分数。

示例请求

{
  "query_text": "帮我找到最相似的字符串！",
  "llm_model_name": "openchat_v3.2_super",
  "similarity_filter_percentage": 0.02,
  "number_of_most_similar_strings_to_return": 5
}

5. /get_all_embedding_vectors_for_document/ (POST)

目的

提取文档的文本嵌入。该库现在支持多种文件类型，包括纯文本、.doc/.docx、PDF 文件、图像（使用 Tesseract OCR）以及 textract 库支持的其他多种类型。

参数

• file: 上传的文档文件（可以是纯文本、.doc/.docx、PDF 等）。
• llm_model_name:（可选）用于计算嵌入的模型。
• json_format:（可选）JSON 响应的格式。
• send_back_json_or_zip_file: 是否返回 JSON 文件或包含嵌入文件的 ZIP 文件（可选，默认为 zip）。
• token: 安全令牌（可选）。

6. /compute_transcript_with_whisper_from_audio/ (POST)

目的

转录音频文件，并可选地为生成的转录文本文档计算嵌入。该端点使用 Whisper 模型进行转录，并使用语言模型生成嵌入。转录和嵌入随后可以被存储，并提供一个包含嵌入的 ZIP 文件供下载。

参数

• file: 需要上传以进行转录的音频文件。
• compute_embeddings_for_resulting_transcript_document: 布尔值，指示是否应计算文档嵌入（可选，默认为 False）。
• llm_model_name: 用于计算嵌入的语言模型（可选，默认为默认模型名称）。
• req: HTTP 请求对象，用于获取额外的请求元数据（可选）。
• token: 安全令牌（可选）。
• client_ip: 客户端 IP 地址（可选）。

请求文件及参数

您需要使用 multipart/form-data 请求上传音频文件。其他参数，如 compute_embeddings_for_resulting_transcript_document 和 llm_model_name，可以作为表单字段一并发送。

示例请求

curl -X 'POST' \
  'http://localhost:8000/compute_transcript_with_whisper_from_audio/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -F 'file=@your_audio_file.wav' \
  -F 'compute_embeddings_for_resulting_transcript_document=true' \
  -F 'llm_model_name=custom-llm-model'

7. /get_text_completions_from_input_prompt/ (POST)

目的

使用指定模型为给定输入提示生成文本补全。

参数

• request: 包含各种选项的 JSON 对象，如 input_prompt、llm_model_name 等。
• token: 安全令牌（可选）。
• req: HTTP 请求对象（可选）。
• client_ip: 客户端 IP 地址（可选）。

请求 JSON 格式

JSON 对象应包含以下键：

• input_prompt
• llm_model_name
• temperature
• grammar_file_string
• number_of_completions_to_generate
• number_of_tokens_to_generate

示例请求

{
  "input_prompt": "17世纪的法国国王：",
  "llm_model_name": "phind-codellama-34b-python-v1",
  "temperature": 0.95,
  "grammar_file_string": "json",
  "number_of_tokens_to_generate": 500,
  "number_of_completions_to_generate": 3
}

8. /get_list_of_available_model_names/ (GET)

目的

获取可用于生成嵌入的可用模型名称列表。

参数

• token: 安全令牌（可选）。

9. /get_all_stored_strings/ (GET)

目的

从数据库中检索所有已存储且已计算嵌入的字符串列表。

参数

• token: 安全令牌（可选）。

10. /get_all_stored_documents/ (GET)

目的

从数据库中检索所有已存储且已计算嵌入的文档列表。

参数

• token: 安全令牌（可选）。

11. /clear_ramdisk/ (POST)

目的

清空 RAM 磁盘以释放内存。

参数

• token: 安全令牌（可选）。

12. /download/{file_name} (GET)

目的

下载包含通过 /compute_transcript_with_whisper_from_audio/ 端点生成的文档嵌入的 ZIP 文件。该下载的 URL 将在音频文件转录端点的 JSON 响应中提供。

参数

• file_name: 您想要下载的 ZIP 文件的名称。

13. /add_new_model/ (POST)

目的

提交新的模型 URL 进行下载和使用。该模型必须为 .gguf 格式，且大小需大于 100 MB，以确保其为有效的模型文件。

参数

• model_url: 模型权重文件的 URL，必须以 .gguf 结尾。
• token: 安全令牌（可选）。

词元级嵌入向量池化

池化方法旨在聚合词元级嵌入，而这些嵌入通常由于句子或文档中词元数量的不同而长度不一。通过将这些词元级嵌入转换为一个固定长度的单一向量，我们可以确保无论输入文本的长度如何，都能以一致的方式进行表示。随后，这个固定长度的向量可以用于各种需要固定大小输入的机器学习模型中。

这些池化方法的主要目标是在保证变换具有确定性且不会扭曲数据的前提下，尽可能多地保留原始词元级嵌入中的有用信息。每种方法都通过应用不同的统计或数学技术来总结词元嵌入，从而实现这一目标。

池化方法说明

1. SVD（奇异值分解）：

   • 工作原理：将从词元嵌入矩阵的奇异值分解中得到的前两个奇异向量拼接在一起。
   • 原理：奇异值分解是一种降维技术，能够捕捉数据中最重要特征。使用前两个奇异向量可以提供一种紧凑的表示形式，同时保留大量关键信息。

2. SVD_First_Four：

   • 工作原理：使用从词元嵌入矩阵的奇异值分解中得到的前四个奇异向量。
   • 原理：通过使用更多的奇异向量，该方法能够捕捉到数据中更多的方差，从而在降维的同时提供更丰富的表示。

3. ICA（独立成分分析）：

   • 工作原理：对嵌入矩阵应用独立成分分析，找出统计上相互独立的成分，然后将其展平。
   • 原理：ICA有助于识别数据中的独立源，提供一种突出这些独立特征的表示。

4. Factor_Analysis（因子分析）：

   • 工作原理：对嵌入矩阵应用因子分析，识别潜在因子，然后将其展平。
   • 原理：因子分析以潜在因子的形式建模数据，提供一种能够捕捉这些潜在影响的摘要表示。

5. Gaussian_Random_Projection：

   • 工作原理：应用高斯随机投影来降低嵌入的维度，然后将其展平。
   • 原理：这种方法能够在快速高效地降低维度的同时，保持点与点之间的成对距离不变，非常适合处理大规模数据集。

---

感谢您对我开源项目的关注！希望对您有所帮助。另外，我的一些商业Web应用也可能对您有帮助，如果您有兴趣的话，欢迎去看看：

YoutubeTranscriptOptimizer.com 让您只需简单粘贴一个YouTube视频链接，就能自动生成不仅非常准确的直接转录文本，还能生成一份经过精心润色、格式优美、可独立于视频使用的书面文档。

这份文档的内容基本与视频中讨论的一致，但读起来更像是正式的文章，而不是单纯的转录稿。此外，您还可以选择根据文档内容生成测验，包括选择题和简答题两种形式。其中，选择题会转化为交互式的HTML文件，方便您发布和分享，用户可以直接在线作答，系统还会自动批改并给出分数。

FixMyDocuments.com 允许您上传任何类型的文档——PDF文件（包括需要OCR处理的扫描版PDF）、MS Word和PowerPoint文件、图片、音频文件（如mp3、m4a等）——并将其转换为采用优质Markdown格式的高度优化版本，同时自动生成HTML和PDF版本。转换完成后，您还可以直接在网站上使用内置的Markdown编辑器对文档进行编辑，系统会保存每次修改的历史记录，并自动重新生成PDF和HTML版本。

除了获得优化后的文档外，您还可以基于原始文档生成多种“衍生文档”：可供在线作答并自动评分的互动选择题测验；美观的演示文稿幻灯片（以PDF或HTML形式呈现，使用LaTeX和Reveal.js制作）；深度摘要、概念思维导图（利用Mermaid图表绘制）及大纲；可根据目标受众定制的教学计划；阅读难度分析以及针对不同年级水平的简化版本（适合为学生简化复杂概念）；还可生成Anki闪卡，既可直接导入Anki应用，也可在网站提供的友好界面中使用，等等。

Swiss Army Llama 快速上手指南

Swiss Army Llama 是一个基于 FastAPI 构建的本地大语言模型（LLM）工具集。它提供了便捷的 REST API，支持文本嵌入（Embedding）、文档处理（含 OCR）、音频转录（Whisper）、高级语义相似度计算以及结构化文本生成等功能。所有计算结果可自动缓存至 SQLite，并可通过 Swagger UI 直接交互。

环境准备

系统要求

• 操作系统：推荐 Ubuntu 22.04 或更高版本。
• 硬件：建议具备 GPU 以加速 LLM 推理（可选），需足够内存加载模型。
• 网络：首次运行需下载模型文件，请确保网络通畅。

前置依赖

在安装 Python 依赖前，需先安装系统级库以支持文档解析、OCR 及音频处理：

sudo apt-get update
sudo apt-get install build-essential libxml2-dev libxslt1-dev antiword unrtf poppler-utils pstotext tesseract-ocr flac ffmpeg lame libmad0 libsox-fmt-mp3 sox libjpeg-dev swig redis-server libpoppler-cpp-dev pkg-config -y

启动 Redis 服务（用于并发请求锁定）：

sudo systemctl enable redis-server
sudo systemctl start redis

安装步骤

你可以选择使用 Python 虚拟环境（推荐）或 Docker 进行部署。以下提供原生 Python 环境的安装流程。

方式一：手动安装（推荐）

1. 克隆项目代码

   git clone https://github.com/Dicklesworthstone/swiss_army_llama
   cd swiss_army_llama
   

2. 创建并激活虚拟环境

   python3 -m venv venv
   source venv/bin/activate
   

3. 升级构建工具并安装依赖 注：国内用户若遇 pip 下载缓慢，可临时添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 参数。

   python3 -m pip install --upgrade pip wheel setuptools
   pip install -r requirements.txt
   

方式二：一键脚本安装（仅限全新 Ubuntu 机器）

如果你在一台全新的 Ubuntu 服务器上，可以使用官方提供的自动化脚本（会自动安装 PyEnv、Python 3.12 及所有依赖）：

git clone https://github.com/Dicklesworthstone/swiss_army_llama && cd swiss_army_llama && chmod +x install_swiss_army_llama.sh && ./install_swiss_army_llama.sh && pyenv local 3.12 && source venv/bin/activate && python swiss_army_llama.py

基本使用

1. 启动服务

在项目根目录下运行主程序：

python swiss_army_llama.py

服务默认监听 0.0.0.0:8089（端口可通过 .env 文件中的 SWISS_ARMY_LLAMA_SERVER_LISTEN_PORT 配置）。

2. 访问交互界面

打开浏览器访问 Swagger UI 界面：

• 本地访问：http://localhost:8089
• 服务器访问：http://<你的服务器 IP>:8089

在界面中，你可以直接测试所有可用接口。

3. 核心功能示例

通过 Swagger UI 或 HTTP 客户端调用以下典型功能：

A. 获取文本嵌入 (Text Embeddings)

调用嵌入接口，输入文本即可返回向量。系统会自动缓存结果，重复请求秒级响应。

• Endpoint: /compute_embeddings
• 特性: 支持多种池化方法（mean, svd, ica 等）。

B. 处理文档与 OCR

上传 PDF、Word 或图片文件，系统自动提取文本（扫描件自动调用 Tesseract OCR），分句并计算嵌入。

• Endpoint: /process_document
• 返回: JSON 数据或包含结果的 ZIP 文件链接。

C. 音频转录与嵌入

上传 MP3 或 WAV 文件，使用 Faster Whisper 模型转录为文本，并可进一步计算句子级嵌入。

• Endpoint: /transcribe_and_embed_audio

D. 高级语义搜索

利用 FAISS 进行初步检索，再结合 Rust 编写的高性能库计算深层相似度（如 Spearman, Hoeffding D 等）。

• Endpoint: /advanced_semantic_search

E. 结构化文本生成

指定 Grammar 文件（如 JSON 格式），让 LLM 生成符合特定结构的回复。

• Endpoint: /generate_completions

4. 配置说明

编辑项目根目录下的 .env 文件可自定义行为，例如：

• USE_SECURITY_TOKEN: 开启安全令牌验证。
• USE_PARALLEL_INFERENCE_QUEUE: 启用并行推理队列。
• MAX_CONCURRENT_PARALLEL_INFERENCE_TASKS: 设置最大并发任务数。

修改配置后重启服务即可生效。