{
"canonical_name": "neuml/txtai",
"compilation_id": "pack_0d8f97742c4f41ebaaae96722cae565b",
"created_at": "2026-05-16T22:35:50.275189+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install txtai` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install txtai",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_e775b5f84bd349b5bde798d510ae5f39"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_7305b996eaf797994230a61ac09ab3d0",
"canonical_name": "neuml/txtai",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/neuml/txtai",
"slug": "txtai",
"source_packet_id": "phit_5dab3b1b35cc4f41b0d3a07d112b355c",
"source_validation_id": "dval_0113bd6941264ce5bd0bac2c55fff767"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 826,
"github_stars": 12570,
"one_liner_en": "💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows",
"one_liner_zh": "💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "txtai",
"title_zh": "txtai 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_5dab3b1b35cc4f41b0d3a07d112b355c",
"page_model": {
"artifacts": {
"artifact_slug": "txtai",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install txtai",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/neuml/txtai#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add `txtai_minimal` package",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4e4050b59fdf4d51ac21e82d248e589e | https://github.com/neuml/txtai/issues/1090 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add `txtai_minimal` package",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Captions implementation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ff6fe05065564e85a549d7656b85a852 | https://github.com/neuml/txtai/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add custom Captions implementation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Questions pipeline implementation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fa68ea29089d497bb8278c3c360c363c | https://github.com/neuml/txtai/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add custom Questions pipeline implementation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Sequences pipeline implementation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_0099afb385ef498d8020521bbf3e9e64 | https://github.com/neuml/txtai/issues/1086 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add custom Sequences pipeline implementation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Summary pipeline implementation",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9d8f75c31fc6450d8659b310f25d0bf4 | https://github.com/neuml/txtai/issues/1085 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add custom Summary pipeline implementation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add minimal Docker build script",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_38e1e56a991b412bbc749d2c0b687d54 | https://github.com/neuml/txtai/issues/1092 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Add minimal Docker build script",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Make `transformers` package optional for minimal install",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_d755829200de4d93b2f4d2f71b36aaf1 | https://github.com/neuml/txtai/issues/1091 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Make `transformers` package optional for minimal install",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Reduce dependencies to just `numpy` for minimal install",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_395b735968ab4ec8ad849070d43cd18f | https://github.com/neuml/txtai/issues/1093 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Reduce dependencies to just `numpy` for minimal install",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support minimal install for edge devices",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_3ec8e039baf4412888ed3ac543ea1361 | https://github.com/neuml/txtai/issues/1089 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Support minimal install for edge devices",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Various training pipeline fixes for v5",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b47325d7496248a993d980c3d59f3269 | https://github.com/neuml/txtai/issues/1088 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Various training pipeline fixes for v5",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Zero dependency minimal install",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_7839a465e7e64f94acfff001c1da978c | https://github.com/neuml/txtai/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Zero dependency minimal install",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v9.9.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8b842ce68a1c4c1ab0a40a3ed1fd213c | https://github.com/neuml/txtai/releases/tag/v9.9.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v9.9.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:286301447 | https://github.com/neuml/txtai | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v9.7.0",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e3f61e41f6e84b9b9ee33d5e18dbff63 | https://github.com/neuml/txtai/releases/tag/v9.7.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v9.7.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add `txtai_minimal` package。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 23,
"forks": 826,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 12570
},
"source_url": "https://github.com/neuml/txtai",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows",
"title": "txtai 能力包",
"trial_prompt": "# txtai - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 txtai 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：txtai概述。围绕“txtai概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n4. page-embeddings：向量嵌入系统。围绕“向量嵌入系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-pipeline-llm：LLM管道。围绕“LLM管道”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“txtai概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-embeddings\n输入：用户提供的“向量嵌入系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-pipeline-llm\n输入：用户提供的“LLM管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“txtai概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-components：Step 3 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-embeddings：Step 4 必须围绕“向量嵌入系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-pipeline-llm：Step 5 必须围绕“LLM管道”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/neuml/txtai\n- https://github.com/neuml/txtai#readme\n- README.md\n- src/python/txtai/__init__.py\n- src/python/txtai/embeddings/base.py\n- src/python/txtai/workflow/base.py\n- src/python/txtai/agent/base.py\n- src/python/txtai/embeddings/__init__.py\n- src/python/txtai/pipeline/__init__.py\n- src/python/txtai/workflow/__init__.py\n- src/python/txtai/agent/__init__.py\n- src/python/txtai/embeddings/index/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 txtai 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Add LiteRT-LM LLM（https://github.com/neuml/txtai/issues/1095）；github/github_issue: Zero dependency minimal install（https://github.com/neuml/txtai/issues/1094）；github/github_issue: Reduce dependencies to just `numpy` for minimal install（https://github.com/neuml/txtai/issues/1093）；github/github_issue: Make `transformers` package optional for minimal install（https://github.com/neuml/txtai/issues/1091）；github/github_issue: Add minimal Docker build script（https://github.com/neuml/txtai/issues/1092）；github/github_issue: Add `txtai_minimal` package（https://github.com/neuml/txtai/issues/1090）；github/github_issue: Various training pipeline fixes for v5（https://github.com/neuml/txtai/issues/1088）；github/github_issue: Add custom Questions pipeline implementation（https://github.com/neuml/txtai/issues/1087）；github/github_issue: Add custom Sequences pipeline implementation（https://github.com/neuml/txtai/issues/1086）；github/github_issue: Add custom Summary pipeline implementation（https://github.com/neuml/txtai/issues/1085）；github/github_issue: Add custom Captions implementation（https://github.com/neuml/txtai/issues/1084）；github/github_issue: Support minimal install for edge devices（https://github.com/neuml/txtai/issues/1089）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Add LiteRT-LM LLM",
"url": "https://github.com/neuml/txtai/issues/1095"
},
{
"kind": "github_issue",
"source": "github",
"title": "Zero dependency minimal install",
"url": "https://github.com/neuml/txtai/issues/1094"
},
{
"kind": "github_issue",
"source": "github",
"title": "Reduce dependencies to just `numpy` for minimal install",
"url": "https://github.com/neuml/txtai/issues/1093"
},
{
"kind": "github_issue",
"source": "github",
"title": "Make `transformers` package optional for minimal install",
"url": "https://github.com/neuml/txtai/issues/1091"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add minimal Docker build script",
"url": "https://github.com/neuml/txtai/issues/1092"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add `txtai_minimal` package",
"url": "https://github.com/neuml/txtai/issues/1090"
},
{
"kind": "github_issue",
"source": "github",
"title": "Various training pipeline fixes for v5",
"url": "https://github.com/neuml/txtai/issues/1088"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add custom Questions pipeline implementation",
"url": "https://github.com/neuml/txtai/issues/1087"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add custom Sequences pipeline implementation",
"url": "https://github.com/neuml/txtai/issues/1086"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add custom Summary pipeline implementation",
"url": "https://github.com/neuml/txtai/issues/1085"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add custom Captions implementation",
"url": "https://github.com/neuml/txtai/issues/1084"
},
{
"kind": "github_issue",
"source": "github",
"title": "Support minimal install for edge devices",
"url": "https://github.com/neuml/txtai/issues/1089"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows",
"effort": "安装已验证",
"forks": 826,
"icon": "code",
"name": "txtai 能力包",
"risk": "可发布",
"slug": "txtai",
"stars": 12570,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"自动化工作流",
"本地优先"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/neuml/txtai 项目说明书\n\n生成时间：2026-05-16 22:15:25 UTC\n\n## 目录\n\n- [txtai概述](#page-overview)\n- [系统架构](#page-architecture)\n- [核心组件](#page-components)\n- [向量嵌入系统](#page-embeddings)\n- [近似最近邻索引](#page-ann-index)\n- [评分系统](#page-scoring)\n- [LLM管道](#page-pipeline-llm)\n- [文本处理管道](#page-pipeline-text)\n- [音频和图像管道](#page-pipeline-audio)\n- [工作流引擎](#page-workflow)\n\n\n\n## txtai概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/neuml/txtai/blob/main/README.md)\n- [setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/embeddings/index/documents.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n- [src/python/txtai/workflow/task/template.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n \n\n# txtai概述\n\n## 1. 项目简介\n\ntxtai是一个全功能AI框架，专为语义搜索、大型语言模型（LLM）编排和语言模型工作流而设计 资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)。\n\n该框架的核心组件是**嵌入数据库（Embeddings Database）**，它将向量索引（稀疏和密集）、图网络和关系数据库结合在一起 资料来源：[README.md:19](https://github.com/neuml/txtai/blob/main/README.md)。\n\n## 2. 核心功能特性\n\ntxtai提供以下主要功能：\n\n| 功能类别 | 描述 |\n|---------|------|\n| 向量搜索 | 支持SQL、对象存储、主题建模、图分析和多模态索引 |\n| 嵌入生成 | 为文本、文档、音频、图像和视频创建嵌入向量 |\n| 管道系统 | 包含LLM提示、问答、标注、转录、翻译等语言模型驱动的管道 |\n| API服务 | 内置FastAPI支持多语言应用开发 |\n| 工作流 | 灵活的工作流引擎支持复杂AI任务编排 |\n| Agent代理 | 构建自主Agent和RAG流程 |\n\n资料来源：[README.md:24-31](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 3. 系统架构\n\n### 3.1 整体架构\n\n```mermaid\ngraph TD\n A[用户应用] --> B[API层 FastAPI]\n B --> C[工作流引擎 Workflow]\n C --> D[管道系统 Pipeline]\n D --> E{任务类型}\n E --> F[数据管道 Data]\n E --> G[LLM管道 LLM]\n E --> H[文本管道 Text]\n E --> I[训练管道 Train]\n F --> J[嵌入数据库 Embeddings]\n G --> J\n J --> K[(向量索引)]\n J --> L[(图网络)]\n J --> M[(关系数据库)]\n```\n\n### 3.2 核心模块关系\n\n```mermaid\ngraph TD\n subgraph 数据处理层\n T[Textractor] --> H2M[HTMLToMarkdown]\n H2M --> SEG[Segmentation]\n end\n \n subgraph 嵌入层\n SEG --> EMB[Embeddings]\n EMB --> DOCS[Documents]\n end\n \n subgraph AI能力层\n EMB --> LLM[LLM Pipeline]\n LLM --> RAG[RAG Pipeline]\n end\n \n subgraph 执行层\n TSK[TemplateTask] --> WFL[Workflow]\n end\n```\n\n## 4. 依赖体系\n\n### 4.1 核心依赖\n\n| 依赖包 | 最低版本 | 用途 |\n|-------|---------|------|\n| faiss-cpu | 1.7.1.post2 | 高效向量相似度搜索 |\n| huggingface-hub | 0.34.0 | Hugging Face模型访问 |\n| torch | 2.4 | 深度学习框架 |\n| transformers | 4.56.2 | 模型推理 |\n| numpy | 1.18.4 | 数值计算 |\n| safetensors | 0.4.5 | 安全模型加载 |\n\n资料来源：[setup.py:28-38](https://github.com/neuml/txtai/blob/main/setup.py)\n\n### 4.2 可选依赖组\n\ntxtai采用模块化设计，通过可选依赖组提供扩展功能：\n\n| 依赖组 | 包含组件 |\n|-------|---------|\n| pipeline-audio | 音频处理管道（onnx, soundfile, webrtcvad等） |\n| pipeline-data | 数据处理管道（beautifulsoup4, docling, nltk等） |\n| pipeline-image | 图像处理管道（pillow, timm, imagehash等） |\n| pipeline-llm | LLM管道（litellm, llama-cpp-python等） |\n| pipeline-text | 文本管道（gliner, sentencepiece等） |\n| pipeline-train | 训练管道（accelerate, peft, onnx等） |\n| agent | Agent代理（jinja2, smolagents, mcpadapt等） |\n| ann | 向量检索（annoy, hnswlib, pgvector等） |\n| api | API服务（fastapi, uvicorn, aiohttp等） |\n| graph | 图数据库（grand-cypher, networkx等） |\n\n资料来源：[setup.py:7-82](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 5. 主要组件详解\n\n### 5.1 嵌入数据库（Embeddings）\n\nEmbeddings是txtai的核心组件，提供向量化的语义搜索能力。\n\n**基本使用示例：**\n\n```python\nimport txtai\n\nembeddings = txtai.Embeddings()\nembeddings.index([\"Correct\", \"Not what we hoped\"])\nresult = embeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md:70-75](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 5.2 文本提取器（Textractor）\n\nTextractor模块负责从各种文件格式中提取文本内容。\n\n```python\nclass Textractor(Segmentation):\n def __init__(\n self,\n sentences=False, # 按句子分割\n lines=False, # 按行分割\n paragraphs=False, # 按段落分割\n minlength=None, # 最小文本长度\n join=False, # 是否合并结果\n sections=False, # 保留章节结构\n cleantext=True, # 清理文本\n chunker=None, # 分块器\n headers=None, # HTTP请求头\n backend=\"available\", # 后端选择\n safeopen=False, # 安全打开模式\n ):\n```\n\n**支持的输入格式：**\n\nTextractor内部使用FileToHTML管道处理文件，并支持Tika后端作为备选方案。\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:15-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n\n### 5.3 LLM管道\n\nLLM管道提供大型语言模型的调用能力，支持多种模型后端。\n\n**核心方法：**\n\n| 方法 | 描述 |\n|------|------|\n| `__call__(text, ...)` | 生成文本内容 |\n| `ischat()` | 检查是否为聊天模型 |\n| `isvision()` | 检查是否支持视觉功能 |\n\n**调用参数：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| text | str/list | - | 输入文本 |\n| maxlength | int | None | 最大序列长度 |\n| stream | bool | False | 是否流式输出 |\n| stop | list | None | 停止字符串列表 |\n| defaultrole | str | \"auto\" | 默认角色 |\n| stripthink | bool | None | 是否去除思考标签 |\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:20-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n\n### 5.4 工作流引擎（Workflow）\n\n工作流引擎支持灵活的任务编排。\n\n**TemplateTask组件：**\n\nTemplateTask使用模板生成LLM提示词，支持字典和元组两种参数传递方式：\n\n```python\n# 字典参数传递\nself.formatter.format(self.template, **element)\n\n# 元组参数传递\nself.formatter.format(self.template, **{f\"arg{i}\": x for i, x in enumerate(element)})\n\n# 默认行为 - 使用{text}参数\nself.formatter.format(self.template, text=element)\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:35-50](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n\n## 6. RAG快速入门\n\n### 6.1 完整流程\n\n```mermaid\ngraph LR\n A[加载文档] --> B[文本提取 Textractor]\n B --> C[文本分块]\n C --> D[构建嵌入索引]\n D --> E[创建RAG管道]\n E --> F[用户提问]\n F --> G[语义检索]\n G --> H[上下文组装]\n H --> I[LLM生成答案]\n```\n\n### 6.2 代码示例\n\n```python\nfrom txtai import Embeddings\nfrom txtai.pipeline import RAG, Textractor\n\n# Step 1: 文本提取\ntextractor = Textractor()\nf = \"document.pdf\"\nchunks = []\nfor chunk in textractor(f):\n chunks.append((f, chunk))\n\n# Step 2: 构建嵌入数据库\nembeddings = Embeddings(\n content=True, \n path=\"Qwen/Qwen3-Embedding-0.6B\", \n maxlength=2048\n)\nembeddings.index(chunks)\n\n# Step 3: 创建RAG管道\ntemplate = \"\"\"\n Answer the following question using the provided context.\n\n Question: {question}\n Context: {context}\n\"\"\"\n\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# Step 4: 问答\nquestion = \"Summarize the main advancements made by BERT\"\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py:1-50](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## 7. 文档存储机制\n\n### 7.1 Documents类\n\nDocuments类负责管理索引文档的存储和序列化：\n\n```python\nclass Documents:\n def add(self, documents):\n \"\"\"添加文档批次\"\"\"\n if not self.documents:\n self.documents = tempfile.NamedTemporaryFile(\n mode=\"wb\", suffix=\".docs\", delete=False\n )\n \n # 流式保存文档\n self.serializer.savestream(documents, self.documents)\n self.batch += 1\n self.size += len(documents)\n return documents\n \n def close(self):\n \"\"\"关闭并清理临时文件\"\"\"\n os.remove(self.documents.name)\n self.documents = None\n self.batch = 0\n self.size = 0\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:10-30](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n## 8. 部署方式\n\n### 8.1 API服务部署\n\n通过YAML配置文件快速启动API服务：\n\n```yaml\n# app.yml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n```\n\n```bash\nCONFIG=app.yml uvicorn \"txtai.api:app\"\ncurl -X GET \"http://localhost:8000/search?query=positive\"\n```\n\n### 8.2 工作流API\n\n```python\ndef api(self, config):\n \"\"\"启动内部uvicorn服务器\"\"\"\n # 生成临时工作流配置文件\n workflow = os.path.join(tempfile.gettempdir(), \"workflow.yml\")\n with open(workflow, \"w\", encoding=\"utf-8\") as f:\n f.write(config)\n \n os.environ[\"CONFIG\"] = workflow\n txtai.api.application.start()\n```\n\n资料来源：[examples/workflows.py:60-75](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n\n## 9. 技术特点\n\n| 特点 | 说明 |\n|------|------|\n| 低占用 | 仅安装必要依赖，可按需扩展 |\n| 本地运行 | 无需将数据发送到外部服务 |\n| 模型兼容 | 支持从小型模型到LLM的多种规模 |\n| 灵活扩展 | 模块化设计，易于集成新功能 |\n| 多模态 | 支持文本、文档、音频、图像和视频 |\n\n资料来源：[README.md:80-85](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 10. 安装方式\n\n### 10.1 基础安装\n\n```bash\npip install txtai\n```\n\n### 10.2 可选组件安装\n\n```bash\n# 仅向量搜索\npip install txtai[ann]\n\n# 包含向量搜索\npip install txtai[vectors]\n\n# 完整安装\npip install txtai[all]\n\n# 特定功能\npip install txtai[api] # API服务\npip install txtai[agent] # Agent代理\npip install txtai[pipeline-llm] # LLM支持\npip install txtai[graph] # 图数据库\n```\n\n资料来源：[setup.py:85-110](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 11. 总结\n\ntxtai是一个功能全面的AI框架，通过将向量搜索、图数据库和关系数据库相结合，为构建语义搜索、RAG系统和AI工作流提供了统一的基础设施。其模块化设计和丰富的可选依赖使其能够适应从简单到复杂的各种应用场景。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件](#page-components), [向量嵌入系统](#page-embeddings), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n- [src/python/txtai/workflow/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/base.py)\n- [src/python/txtai/agent/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/base.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/embeddings/index/documents.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n- [examples/workflows.py](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n \n\n# 系统架构\n\n## 概述\n\ntxtai 是一个功能全面的 AI 框架，核心定位为**语义搜索**、**LLM 编排**和**语言模型工作流**的一体化解决方案。该框架的关键组件是**嵌入数据库（Embeddings Database）**，它整合了向量索引（稀疏和密集）、图网络和关系数据库的能力。\n\n这种架构设计使得 txtai 不仅能够执行向量搜索，还能作为大型语言模型（LLM）应用的强大知识源，支持构建自主代理（Agents）、检索增强生成（RAG）流程、多模态工作流等高级应用场景。\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 整体架构\n\ntxtai 采用模块化设计，核心架构由以下几个主要层次组成：\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n API[API 服务层]\n Console[Console 控制台]\n end\n \n subgraph \"应用层\"\n Agent[Agent 代理]\n Workflow[Workflow 工作流]\n RAG[RAG 管道]\n end\n \n subgraph \"管道层\"\n LLM[LLM 管道]\n Data[Data 数据管道]\n Text[Text 文本管道]\n Audio[Audio 音频管道]\n Image[Image 图像管道]\n end\n \n subgraph \"核心层\"\n Embeddings[Embeddings 嵌入数据库]\n Graph[Graph 图网络]\n Database[Database 数据库]\n end\n \n subgraph \"向量索引层\"\n FAISS[FAISS]\n HNSW[HNSWLib]\n Annoy[Annoy]\n PGVector[PGVector]\n end\n \n API --> Agent\n API --> Workflow\n Agent --> Workflow\n Workflow --> Embeddings\n Workflow --> LLM\n RAG --> Embeddings\n RAG --> LLM\n Embeddings --> FAISS\n Embeddings --> HNSW\n Embeddings --> Annoy\n Embeddings --> PGVector\n Embeddings --> Graph\n Embeddings --> Database\n```\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 核心模块\n\n### 1. 嵌入数据库（Embeddings）\n\n嵌入数据库是 txtai 的核心组件，它统一了向量索引、图网络和关系数据库的功能。\n\n#### 核心类结构\n\n```python\nclass Embeddings:\n def __init__(self, content=True, path=\"model\", maxlength=2048):\n self.content = content\n self.path = path\n self.maxlength = maxlength\n \n def index(self, documents): ...\n def search(self, query, limit=10): ...\n def batch(self, documents): ...\n```\n\n#### 功能特性\n\n| 特性 | 描述 | 支持类型 |\n|------|------|----------|\n| 向量搜索 | 稀疏和密集向量索引 | FAISS, HNSW, Annoy, PGVector |\n| 内容存储 | 文档内容持久化 | msgpack 序列化 |\n| SQL 查询 | 混合搜索能力 | SQLAlchemy |\n| 图分析 | 图网络遍历 | NetworkX, Grand |\n| 多模态 | 支持多种数据类型 | 文本、图像、音视频 |\n\n资料来源：[src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n\n#### 文档存储机制\n\n嵌入数据库使用临时文件系统存储文档数据，支持批量索引操作：\n\n```python\n# documents.py 中的关键实现\nif not self.documents:\n self.documents = tempfile.NamedTemporaryFile(mode=\"wb\", suffix=\".docs\", delete=False)\n\n# 批量添加文档\nself.serializer.savestream(documents, self.documents)\nself.batch += 1\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:2-15](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n### 2. 工作流引擎（Workflow）\n\n工作流引擎负责编排和组织多个任务（Task）的执行流程。\n\n#### 工作流结构\n\n```mermaid\ngraph LR\n subgraph \"工作流定义\"\n Config[YAML 配置]\n Tasks[任务列表]\n end\n \n subgraph \"任务类型\"\n Action[Action 动作]\n Service[Service 服务]\n Transform[Transform 转换]\n end\n \n Config --> Tasks\n Tasks --> Action\n Tasks --> Service\n Tasks --> Transform\n```\n\n#### 支持的任务类型\n\n| 任务类型 | 说明 | 配置方式 |\n|----------|------|----------|\n| `action` | 执行动作任务 | `{\"action\": \"taskname\"}` |\n| `service` | 启动服务任务 | `{\"task\": \"service\"}` |\n| `textractor` | 文本提取任务 | `{\"action\": \"textractor\", \"task\": \"url\"}` |\n| `transcription` | 音频转录任务 | `{\"action\": \"transcription\", \"task\": \"url\"}` |\n| `tabular` | 表格处理任务 | `{\"action\": \"tabular\"}` |\n| `summary` | 摘要生成任务 | `{\"action\": \"summary\", \"path\": \"model\"}` |\n\n资料来源：[examples/workflows.py](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n\n#### 模板任务（Template Task）\n\n模板任务用于生成 LLM 提示词，支持多种输入格式：\n\n```python\nclass TemplateTask(Task):\n def prepare(self, element):\n # 字典输入 - 作为命名参数传递\n if isinstance(element, dict):\n return self.formatter.format(self.template, **element)\n \n # 元组输入 - 作为 arg0-argN 传递\n if isinstance(element, tuple):\n return self.formatter.format(self.template, **{f\"arg{i}\": x for i, x in enumerate(element)})\n \n # 默认 - 使用 {text} 参数\n return self.formatter.format(self.template, text=element)\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:30-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n\n### 3. 代理系统（Agent）\n\n代理系统支持构建自主 AI 代理，具备规划、推理和执行能力。\n\n```mermaid\ngraph TD\n Agent[Agent 代理] --> Tool1[工具 1]\n Agent --> Tool2[工具 2]\n Agent --> ToolN[工具 N]\n Agent --> LLM[LLM 引擎]\n \n Tool1 --> Memory[记忆存储]\n Tool2 --> Memory\n ToolN --> Memory\n \n LLM --> Action[执行动作]\n Action --> Tool1\n Action --> Tool2\n Action --> ToolN\n```\n\n#### 代理特性\n\n- 支持多种 LLM 后端（Hugging Face、Ollama、vLLM、llama.cpp）\n- 集成 MCP（Model Context Protocol）适配器\n- 支持 Jinja2 模板渲染\n- 可与工作流系统无缝集成\n\n资料来源：[src/python/txtai/agent/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/base.py)\n\n### 4. 管道系统（Pipeline）\n\n管道系统是数据处理的核心，提供多种专门的处理器。\n\n#### 管道类型\n\n| 管道类型 | 功能 | 依赖库 |\n|----------|------|--------|\n| LLM 管道 | 语言模型推理、提示执行 | transformers, llama-cpp |\n| Data 管道 | 文本提取、HTML 转换、分段 | beautifulsoup4, tika, nltk |\n| Audio 管道 | 语音转文本、翻译 | scipy, soundfile |\n| Image 管道 | 图像处理、特征提取 | pillow, timm |\n| Text 管道 | 文本分类、实体识别 | gliner, staticvectors |\n\n#### 文本提取器（Textractor）\n\n文本提取器是数据管道的重要组成部分，支持从多种格式提取文本：\n\n```python\nclass Textractor(Segmentation):\n def __init__(\n self,\n sentences=False, # 句子分割\n lines=False, # 行分割\n paragraphs=False, # 段落分割\n minlength=None, # 最小文本长度\n join=False, # 合并短文本\n sections=False, # 保留章节结构\n cleantext=True, # 清理文本\n chunker=None, # 分块器\n backend=\"available\", # 后端: tika 或自动\n safeopen=False, # 安全打开模式\n ):\n```\n\n处理流程：\n\n```mermaid\ngraph LR\n Input[输入文件/URL] --> FileToHTML[FileToHTML]\n FileToHTML --> HTMLToMarkdown[HTMLToMarkdown]\n HTMLToMarkdown --> Segmentation[Segmentation]\n Segmentation --> Output[文本输出]\n```\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:14-40](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n\n#### LLM 管道\n\nLLM 管道负责与语言模型交互：\n\n```python\nclass LLM:\n def __call__(\n self,\n text, # 输入文本或列表\n maxlength=None, # 最大序列长度\n stream=False, # 流式响应\n stop=None, # 停止字符串列表\n defaultrole=\"auto\", # 默认角色\n stripthink=True, # 移除思考标签\n **kwargs # 其他生成参数\n ):\n return self.generator(text, maxlength, stream, stop, defaultrole, stripthink, **kwargs)\n \n def ischat(self): ... # 检查是否为聊天模型\n def isvision(self): ... # 检查是否支持视觉\n```\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:20-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n\n## 应用场景架构\n\n### 检索增强生成（RAG）\n\n```mermaid\ngraph TD\n Question[用户问题] --> Embeddings[Embeddings 查询]\n Embeddings --> Context[上下文检索]\n Context --> LLM[LLM 生成]\n LLM --> Answer[生成回答]\n \n subgraph \"索引流程\"\n Documents[文档] --> Textractor[文本提取]\n Textractor --> Chunks[文本块]\n Chunks --> Index[向量索引]\n end\n```\n\nRAG 应用示例：\n\n```python\n# 创建嵌入数据库\nembeddings = Embeddings(content=True, path=\"Qwen/Qwen3-Embedding-0.6B\", maxlength=2048)\nembeddings.index(chunks)\n\n# 创建 RAG 管道\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# 执行查询\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n### API 服务架构\n\n```mermaid\ngraph LR\n Request[HTTP 请求] --> FastAPI[FastAPI 服务]\n FastAPI --> Workflow[Workflow 引擎]\n Workflow --> Pipeline[Pipeline 管道]\n Pipeline --> Embeddings[Embeddings]\n Pipeline --> LLM[LLM]\n Workflow --> Response[JSON 响应]\n```\n\nAPI 配置示例（YAML）：\n\n```yaml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n\nworkflow:\n search:\n tasks:\n - action: similarity\n```\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 依赖关系\n\ntxtai 的依赖组织结构如下：\n\n```mermaid\ngraph TD\n Core[核心依赖] --> Torch[torch>=2.4]\n Core --> Transformers[transformers>=4.56.2]\n Core --> Faiss[faiss-cpu>=1.7.1]\n Core --> HuggingFace[huggingface-hub>=0.34.0]\n \n Optional[可选依赖] --> API[API: fastapi, uvicorn]\n Optional --> ANN[ANN: hnswlib, annoy, pgvector]\n Optional --> LLM[LLM: litellm, llama-cpp]\n Optional --> Cloud[Cloud: apache-libcloud]\n```\n\n## 扩展组件\n\n| 组件类别 | 包名 | 主要功能 |\n|----------|------|----------|\n| 图数据库 | `graph` | Grand-Cypher 图查询 |\n| 关系数据库 | `database` | DuckDB, SQLAlchemy |\n| 向量索引 | `ann` | 多种 ANN 算法支持 |\n| 云存储 | `cloud` | Apache Libcloud 集成 |\n| 模型优化 | `model` | ONNX 推理优化 |\n\n## 配置选项\n\n### Embeddings 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `path` | str | - | 模型路径（Hugging Face 模型名或本地路径） |\n| `content` | bool | False | 是否存储原始内容 |\n| `maxlength` | int | 256 | 最大序列长度 |\n| `functions` | dict | None | 函数调用配置 |\n| `scoring` | str | None | 评分方法 |\n| `indextype` | str | None | 索引类型（hnsw, annoy, faiss 等） |\n\n### Workflow 任务配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `action` | str | 任务动作名称 |\n| `task` | str | 任务类型 |\n| `args` | list | 位置参数 |\n| `config` | dict | 任务特定配置 |\n\n## 总结\n\ntxtai 采用分层模块化架构设计，核心优势包括：\n\n1. **统一性**：通过 Embeddings 数据库统一向量搜索、图分析和关系查询\n2. **可扩展性**：丰富的可选依赖支持按需扩展功能\n3. **灵活性**：Pipeline 管道支持自定义数据处理流程\n4. **生产级**：内置 API 服务支持快速部署\n\n该架构设计使得 txtai 能够从小型嵌入模型无缝扩展到完整的 LLM 应用，满足从原型开发到生产部署的全流程需求。\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [向量嵌入系统](#page-embeddings), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/__init__.py)\n- [src/python/txtai/pipeline/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/__init__.py)\n- [src/python/txtai/workflow/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/__init__.py)\n- [src/python/txtai/agent/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/__init__.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/agent/tool/function.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/tool/function.py)\n- [src/python/txtai/agent/tool/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/tool/factory.py)\n \n\n# 核心组件\n\ntxtai 是一个功能全面的 AI 框架，其核心架构由四个主要组件构成：嵌入向量数据库（Embeddings）、管道（Pipeline）、工作流（Workflow）和智能体（Agent）。这些组件协同工作，为语义搜索、大型语言模型（LLM）应用和知识图谱分析提供统一的基础设施。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[txtai 核心架构] --> B[Embeddings 嵌入向量数据库]\n A --> C[Pipeline 管道]\n A --> D[Workflow 工作流]\n A --> E[Agent 智能体]\n \n B --> B1[向量索引]\n B --> B2[图网络]\n B --> B3[关系数据库]\n \n C --> C1[LLM 管道]\n C --> C2[Summary 摘要]\n C --> C3[Textractor 文本提取]\n C --> C4[RAG 检索增强生成]\n \n D --> D1[Task 任务]\n D --> D2[Template 模板]\n \n E --> E1[Tool 工具]\n E --> E2[FunctionTool 函数工具]\n```\n\n## 1. 嵌入向量数据库（Embeddings）\n\n### 概述\n\n嵌入向量数据库是 txtai 的核心组件，它将向量索引（稀疏和密集）、图网络和关系数据库有机结合。这种独特的架构设计使得 txtai 能够同时支持向量搜索和传统数据库查询，为大型语言模型应用提供强大的知识源支持。\n\n### 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 向量搜索 | 支持语义相似度检索 |\n| 混合索引 | 稀疏与密集向量结合 |\n| SQL 支持 | 关系型数据查询 |\n| 图分析 | 知识图谱网络分析 |\n| 内容存储 | 文档和元数据存储 |\n\n### 使用方式\n\n```python\nimport txtai\n\nembeddings = txtai.Embeddings()\nembeddings.index([\"Correct\", \"Not what we hoped\"])\nresult = embeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md]()\n\n## 2. 管道（Pipeline）\n\n### 概述\n\n管道是 txtai 中用于处理数据的核心模块，由语言模型驱动。管道可以执行 LLM 提示、问答、标注、转录、翻译等任务。\n\n### LLM 管道\n\nLLM 管道是 txtai 中最重要的管道之一，支持多种模型类型和调用方式。\n\n#### 支持的模型类型\n\n- Hugging Face Transformers 模型\n- llama.cpp 本地模型\n- Ollama 远程模型\n- vLLM 服务\n\n#### API 参数\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| text | str/list | 必需 | 输入文本或文本列表 |\n| maxlength | int | 512 | 最大序列长度 |\n| stream | bool | False | 是否流式输出 |\n| stop | list | None | 停止字符串列表 |\n| defaultrole | str | \"auto\" | 默认角色（user/prompt） |\n| stripthink | bool | 自动 | 是否移除思考标签 |\n\n```python\nfrom txtai.pipeline import Summary, Textractor\n\n# 文本摘要管道\nsummary = Summary(\"sshleifer/distilbart-cnn-12-6\")\n\n# 文本提取管道\ntextract = Textractor(paragraphs=True, minlength=100, join=True)\n```\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:1-80]()\n\n### 数据管道\n\nTextractor 模块负责从各种文件格式中提取文本内容。\n\n#### Textractor 参数\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| sentences | bool | False | 按句子分割 |\n| lines | bool | False | 按行分割 |\n| paragraphs | bool | False | 按段落分割 |\n| minlength | int | None | 最小文本长度 |\n| join | bool | False | 合并结果 |\n| sections | bool | False | 按章节处理 |\n| cleantext | bool | True | 清理文本 |\n| chunker | str | None | 分块器 |\n| backend | str | \"available\" | 后端（tika/none） |\n| safeopen | bool/str | False | 安全打开模式 |\n\n```python\ntextractor = Textractor(\n paragraphs=True,\n minlength=100,\n join=True,\n backend=\"available\"\n)\n```\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:1-60]()\n\n## 3. 工作流（Workflow）\n\n### 概述\n\n工作流系统允许将多个任务串联起来处理数据。通过定义任务序列，可以构建复杂的数据处理管道。\n\n```mermaid\ngraph LR\n A[输入数据] --> B[Task 1]\n B --> C[Task 2]\n C --> D[Task N]\n D --> E[输出结果]\n```\n\n### 任务类型\n\n| 任务类型 | 描述 |\n|----------|------|\n| Task | 基础任务 |\n| TemplateTask | 模板任务，用于生成 LLM 提示 |\n| UrlTask | URL 处理任务 |\n\n### 模板任务\n\nTemplateTask 是工作流中的重要组件，用于根据模板和任务输入生成文本。模板可以用于准备 LLM 提示数据。\n\n```python\nfrom txtai.workflow import UrlTask, Task, Workflow\n\n# 定义工作流\nworkflow = Workflow([UrlTask(textract), Task(summary)])\n\n# 执行工作流\nresult = list(workflow([url]))[0]\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:1-50]()\n\n## 4. 智能体（Agent）\n\n### 概述\n\n智能体系统用于构建自主代理，支持构建检索增强生成（RAG）流程、多模态工作流等高级应用。\n\n```mermaid\ngraph TD\n A[Agent 智能体] --> B[Tool 工具集]\n A --> C[LLM 大语言模型]\n B --> D[FunctionTool 函数工具]\n B --> E[EmbeddingsTool 嵌入工具]\n C --> F[推理引擎]\n \n F --> G[规划决策]\n G --> H[工具调用]\n H --> I[结果反馈]\n I --> F\n```\n\n### 工具系统\n\ntxtai 的工具系统支持三种创建方式：\n\n| 创建方式 | 描述 |\n|----------|------|\n| Tool 实例 | 直接传入 Tool 对象 |\n| 字典配置 | 包含 name、description、inputs、target 的配置字典 |\n| 字符串别名 | 使用预定义的工具名称 |\n\n#### FunctionTool 类\n\nFunctionTool 将描述性配置与目标函数结合，注入到 LLM 提示中。\n\n```python\nfrom txtai.agent.tool.function import FunctionTool\n\nconfig = {\n \"name\": \"my_function\",\n \"description\": \"执行特定操作\",\n \"inputs\": {\"param1\": \"string\"},\n \"output\": \"string\",\n \"target\": my_function\n}\n\ntool = FunctionTool(config)\n```\n\n资料来源：[src/python/txtai/agent/tool/function.py:1-60]()\n\n### 工具工厂\n\nToolFactory 负责根据配置创建工具实例，支持以下功能：\n\n- 从函数和文档创建工具\n- 从输入字典创建工具\n- 从字符串别名获取默认工具\n- 导入 MCP 工具集合\n\n```python\nfrom txtai.agent.tool.factory import ToolFactory\n\n# 创建工具列表\ntools = ToolFactory.create(config)\n```\n\n资料来源：[src/python/txtai/agent/tool/factory.py:1-80]()\n\n## 5. RAG 检索增强生成\n\n### 概述\n\nRAG 是 txtai 中的重要应用模式，它将嵌入向量数据库与 LLM 结合，实现基于知识库的问答系统。\n\n```mermaid\ngraph TD\n A[用户问题] --> B[Embeddings 查询]\n B --> C[检索相关上下文]\n C --> D[构建提示模板]\n D --> E[LLM 生成答案]\n E --> F[返回结果]\n```\n\n### 使用示例\n\n```python\nfrom txtai import Embeddings, RAG\n\n# 用户提示模板\ntemplate = \"\"\"\n Answer the following question using the provided context.\n\n Question:\n {question}\n\n Context:\n {context}\n\"\"\"\n\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\nquestion = \"Summarize the main advancements made by BERT\"\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py]()\n\n## 组件依赖关系\n\n```mermaid\ngraph TD\n subgraph 核心层\n A[txtai] --> B[Embeddings]\n A --> C[Pipeline]\n A --> D[Workflow]\n A --> E[Agent]\n end\n \n subgraph 管道层\n C --> C1[LLM Pipeline]\n C --> C2[Summary Pipeline]\n C --> C3[Textractor Pipeline]\n C --> C4[RAG Pipeline]\n end\n \n subgraph 应用层\n E --> F[RAG 应用]\n E --> G[自主代理]\n D --> H[数据处理]\n end\n \n B --> I[向量索引]\n B --> J[关系数据库]\n```\n\n## 总结\n\ntxtai 的四大核心组件构成了一个完整的 AI 应用开发框架：\n\n1. **Embeddings** 提供向量搜索和知识存储能力\n2. **Pipeline** 提供数据处理和模型推理能力\n3. **Workflow** 提供任务编排和工作流自动化\n4. **Agent** 提供智能体和自主决策能力\n\n这些组件可以独立使用，也可以组合使用来构建复杂的 AI 应用，如 RAG 系统、多模态工作流和自主代理。\n\n---\n\n\n\n## 向量嵌入系统\n\n### 相关页面\n\n相关主题：[近似最近邻索引](#page-ann-index), [评分系统](#page-scoring), [核心组件](#page-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/__init__.py)\n- [src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n- [src/python/txtai/embeddings/index/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/__init__.py)\n- [src/python/txtai/embeddings/search/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/search/__init__.py)\n- [README.md](https://github.com/neuml/txtai/blob/main/README.md)\n- [setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n \n\n# 向量嵌入系统\n\n## 概述\n\ntxtai 的核心组件是**向量嵌入系统（Embeddings System）**，它是一个将向量索引、图网络和关系数据库统一结合的嵌入数据库。该系统为语义搜索和大语言模型（LLM）应用提供了强大的知识检索基础。\n\n向量嵌入系统的主要特点包括：\n\n- 支持文本、文档、音视频等多模态内容的嵌入表示\n- 集成稀疏和密集向量索引\n- 支持向量搜索与 SQL 查询的混合检索\n- 提供本地化运行能力，无需依赖外部远程服务\n- 支持从小型模型到大型语言模型（LLM）的多种配置\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 系统架构\n\n向量嵌入系统的架构设计采用分层模块化结构，核心由索引模块、搜索模块和基础抽象层组成。\n\n```mermaid\ngraph TD\n A[\"txtai.Embeddings
入口类\"] --> B[\"EmbeddingsBase
基础抽象类\"]\n B --> C[\"EmbeddingsIndex
索引管理\"]\n B --> D[\"EmbeddingsSearch
搜索管理\"]\n C --> E[\"Documents
文档序列化\"]\n C --> F[\"Vectors
向量存储\"]\n D --> G[\"VectorQueue
向量队列\"]\n D --> H[\"HNSW/FAISS等
索引后端\"]\n```\n\n### 核心模块职责\n\n| 模块 | 职责 | 主要功能 |\n|------|------|----------|\n| `Embeddings` | 入口类 | 提供 `index()`、`search()` 等核心 API |\n| `EmbeddingsBase` | 基础抽象 | 定义通用接口和默认实现 |\n| `EmbeddingsIndex` | 索引管理 | 管理文档和向量的索引构建流程 |\n| `EmbeddingsSearch` | 搜索管理 | 处理向量相似度搜索请求 |\n| `Documents` | 文档序列化 | 将输入数据序列化为流式存储格式 |\n\n## Embeddings 入口类\n\n`txtai.Embeddings` 是用户使用向量嵌入系统的主要入口点，提供了简洁的 API 接口。\n\n### 基础使用示例\n\n```python\nimport txtai\n\n# 创建嵌入实例\nembeddings = txtai.Embeddings()\n\n# 索引文档\nembeddings.index([\"正确\", \"不是我们希望的\"])\n\n# 执行语义搜索\nembeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md:1-12](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 构造函数参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `path` | str | None | 向量模型路径，支持 Hugging Face 模型、llama.cpp、Ollama、vLLM |\n| `content` | bool | False | 是否存储原始文档内容 |\n| `vectors` | str | None | 外部向量文件路径 |\n| `functions` | list | None | 自定义向量生成函数列表 |\n| `scoring` | bool | True | 是否启用相似度评分 |\n| `gpu` | bool | True | 是否优先使用 GPU |\n| `batchsize` | int | 32 | 批处理大小 |\n| `maxlength` | int | 512 | 最大序列长度 |\n| `quantize` | bool | False | 是否量化模型 |\n\n资料来源：[examples/rag_quickstart.py:18-19](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## 索引构建流程\n\n### 索引 API\n\n```python\n# 使用 content=True 存储原始文档\nembeddings = Embeddings(content=True, path=\"Qwen/Qwen3-Embedding-0.6B\", maxlength=2048)\nembeddings.index(chunks)\n```\n\n索引过程接受元组列表 `(id, data, vector)` 或 `(id, data)` 格式的数据，自动生成向量表示。\n\n资料来源：[examples/rag_quickstart.py:18-20](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n### 文档序列化\n\n索引模块使用流式序列化机制处理文档数据：\n\n```python\n# Documents 类负责序列化\nself.documents = tempfile.NamedTemporaryFile(mode=\"wb\", suffix=\".docs\", delete=False)\nself.serializer.savestream(documents, self.documents)\n```\n\n序列化设计支持增量索引，可以分批次添加文档：\n\n```python\n# 分批添加文档\nself.batch += 1\nself.size += len(documents)\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:2-10](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n### 索引关闭与清理\n\n索引完成后，系统会清理临时资源：\n\n```python\ndef close(self):\n # 清理流文件\n os.remove(self.documents.name)\n # 重置文档参数\n self.documents = None\n self.batch = 0\n self.size = 0\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:22-30](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n## 搜索流程\n\n### 语义搜索 API\n\n```python\n# 执行向量相似度搜索\nresults = embeddings.search(\"查询文本\", topk=5)\n```\n\n搜索返回格式为 `[(document_id, score), ...]`，按相似度降序排列。\n\n### 向量队列机制\n\n搜索模块使用 `VectorQueue` 管理搜索请求队列，支持并发搜索操作。\n\n```mermaid\ngraph LR\n A[\"search(query)\"] --> B[\"VectorQueue
请求队列\"]\n B --> C[\"HNSW/FAISS
向量索引\"]\n C --> D[\"排序过滤\"]\n D --> E[\"返回结果\"]\n```\n\n### 支持的向量索引后端\n\n| 后端 | 安装包 | 说明 |\n|------|--------|------|\n| FAISS | `faiss-cpu>=1.7.1.post2` | 默认后端，高性能稠密向量检索 |\n| HNSW | `hnswlib>=0.5.0` | 层次可导航小世界图 |\n| Annoy | `annoy>=1.16.3` | Spotify 的近似最近邻库 |\n| pgvector | `pgvector>=0.4.1` | PostgreSQL 向量扩展 |\n\n资料来源：[setup.py:15-40](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 配置与扩展\n\n### 模型路径配置\n\ntxtai 支持多种模型格式和来源：\n\n```yaml\n# app.yml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n```\n\n```python\n# 支持的配置方式\nembeddings = Embeddings(path=\"sentence-transformers/all-MiniLM-L6-v2\")\nembeddings = Embeddings(path=\"Qwen/Qwen3-Embedding-0.6B\") # Hugging Face 模型\nembeddings = Embeddings(path=\"llama.cpp/model.bin\") # 本地 llama.cpp 模型\n```\n\n### 依赖安装\n\n核心依赖（默认安装）：\n\n```python\ndefault = [\n \"faiss-cpu>=1.7.1.post2\",\n \"huggingface-hub>=0.34.0\",\n \"msgpack>=1.0.7\",\n \"numpy>=1.18.4\",\n \"regex>=2022.8.17\",\n \"pyyaml>=5.3\",\n \"safetensors>=0.4.5\",\n \"torch>=2.4\",\n \"transformers>=4.56.2\",\n]\n```\n\n向量索引扩展依赖：\n\n```python\nextras[\"ann\"] = [\n \"annoy>=1.16.3\",\n \"hnswlib>=0.5.0\",\n \"pgvector>=0.4.1\",\n \"scikit-learn>=0.23.1\",\n \"scipy>=1.4.1\",\n]\n\nextras[\"vectors\"] = [\n \"model2vec>=0.3.0\",\n \"sentence-transformers>=5.0.0\",\n \"staticvectors>=0.2.0\",\n]\n```\n\n资料来源：[setup.py:15-30](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 与 RAG 系统集成\n\n向量嵌入系统是检索增强生成（RAG）的基础组件，负责从知识库中检索相关上下文。\n\n```python\n# 创建 RAG 管道\nrag = RAG(\n embeddings, # 嵌入数据库\n \"Qwen/Qwen3-0.6B\", # LLM 模型\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# 执行问答\nresult = rag(\"Summarize BERT advancements\", maxlength=2048, stripthink=True)\n```\n\n工作流程：\n\n```mermaid\ngraph TD\n A[\"用户问题\"] --> B[\"Embeddings.search
向量检索\"]\n B --> C[\"获取相关文档\"]\n C --> D[\"组装提示词\"]\n D --> E[\"LLM 生成回答\"]\n E --> F[\"返回结果\"]\n```\n\n资料来源：[examples/rag_quickstart.py:27-38](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## API 方法参考\n\n### 核心方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `index(docs)` | list | None | 构建向量索引 |\n| `search(query, limit)` | str, int | list | 执行语义搜索 |\n| `batchindex(docs)` | list | None | 批量构建索引 |\n| `batchsearch(queries, limit)` | list, int | list | 批量搜索 |\n| `save(path)` | str | None | 保存索引到磁盘 |\n| `load(path)` | str | None | 从磁盘加载索引 |\n| `upsert(docs)` | list | None | 更新/插入文档 |\n| `delete(ids)` | list | None | 删除文档 |\n\n### 相似度计算\n\n默认使用余弦相似度进行向量相似度计算，搜索结果按相似度降序排列。分数范围通常为 `[0, 1]`，值越接近 1 表示相似度越高。\n\n## 性能优化建议\n\n1. **批量处理**：使用 `batchindex()` 替代多次 `index()` 调用，减少模型加载开销\n2. **序列长度**：根据实际需求调整 `maxlength`，较短的序列处理速度更快\n3. **GPU 加速**：确保 CUDA 环境配置正确，GPU 模式可显著提升吞吐量\n4. **索引后端选择**：数据量较小时使用 FAISS，超过百万向量时考虑 HNSW\n\n## 与其他系统的比较\n\ntxtai 向量嵌入系统与其他向量数据库的关键差异：\n\n| 特性 | txtai | 专用向量数据库 |\n|------|-------|---------------|\n| 部署复杂度 | 单库部署 | 通常需要独立服务 |\n| 功能范围 | 向量+全文+图谱 | 主要聚焦向量检索 |\n| 集成 LLM | 原生支持 | 需额外集成 |\n| SQL 支持 | 内置 | 部分支持 |\n| 扩展性 | 中等 | 高 |\n\n## 总结\n\ntxtai 的向量嵌入系统提供了一个功能完整、易于使用的语义搜索基础设施。通过模块化的设计，用户可以灵活选择向量模型、索引后端和存储方案。系统与 RAG、工作流引擎、API 服务等组件深度集成，能够支撑从简单语义搜索到复杂 LLM 应用的全场景需求。\n\n---\n\n\n\n## 近似最近邻索引\n\n### 相关页面\n\n相关主题：[向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/ann/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/__init__.py)\n- [src/python/txtai/ann/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/base.py)\n- [src/python/txtai/ann/dense/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/dense/__init__.py)\n- [src/python/txtai/ann/dense/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/dense/factory.py)\n \n\n# 近似最近邻索引\n\n## 概述\n\n近似最近邻索引（Approximate Nearest Neighbor，简称 ANN）是 txtai 语义搜索能力的核心组件。该模块提供了在大规模向量数据中进行高效相似性搜索的功能，通过近似算法在精度和性能之间取得平衡。ANN 索引能够将高维向量映射到低维空间，使得在数百万甚至数十亿向量规模下的最近邻查询成为可能，而无需遍历整个数据集。\n\ntxtai 的 ANN 模块设计遵循模块化架构，支持多种后端实现，包括 Faiss、Annoy、Hnswlib 等主流向量索引库。索引系统与 txtai 的数据管道紧密集成，支持动态构建和增量更新。\n\n## 架构设计\n\n### 核心组件层次\n\n```mermaid\ngraph TD\n A[ANN API] --> B[基类 Ann]\n B --> C[Dense ANN]\n C --> D[Faiss Backend]\n C --> E[Annoy Backend]\n C --> F[Hnswlib Backend]\n C --> G[Scann Backend]\n B --> H[Graph ANN]\n D --> I[IndexFactory]\n```\n\n### 目录结构\n\n```\nsrc/python/txtai/ann/\n├── __init__.py # 模块导出和公共 API\n├── base.py # 基类 Ann 定义\n├── dense/ # 密集向量 ANN 实现\n│ ├── __init__.py\n│ └── factory.py # 索引工厂类\n└── graph/ # 图结构 ANN 实现\n └── __init__.py\n```\n\n资料来源：[src/python/txtai/ann/__init__.py:1-20]()\n\n## 基类设计\n\n### Ann 基类接口\n\n`Ann` 基类定义了所有 ANN 实现必须遵循的统一接口，确保不同后端之间的可替换性。\n\n```python\nclass Ann:\n def __init__(self, path=None, method=None, components=None, **kwargs):\n # 初始化索引配置\n pass\n \n def index(self, documents):\n # 构建索引\n pass\n \n def search(self, query, limit=10):\n # 执行搜索查询\n pass\n \n def load(self, path):\n # 从磁盘加载索引\n pass\n \n def save(self, path):\n # 将索引保存到磁盘\n pass\n```\n\n资料来源：[src/python/txtai/ann/base.py:1-50]()\n\n### 核心方法规范\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `index` | `documents: List[Dict]` | `None` | 构建向量索引 |\n| `search` | `query: ndarray, limit: int` | `List[Tuple[int, float]]` | 搜索最近邻 |\n| `load` | `path: str` | `None` | 加载持久化索引 |\n| `save` | `path: str` | `None` | 保存索引到磁盘 |\n| `reset` | `None` | `None` | 清空索引数据 |\n\n## 密集向量索引\n\n### DenseAnn 实现\n\n`DenseAnn` 类是处理密集向量（dense vectors）的主流实现，支持多种后端算法。\n\n```python\nclass DenseAnn(Ann):\n def __init__(self, path=None, method=None, components=None, **kwargs):\n self.method = method\n self.components = components\n self.ann = None # 后端索引实例\n```\n\n资料来源：[src/python/txtai/ann/dense/__init__.py:1-30]()\n\n### 索引工厂模式\n\n`IndexFactory` 采用工厂模式根据配置动态创建合适的索引后端实例。\n\n```python\nclass IndexFactory:\n @staticmethod\n def create(config):\n method = config.get(\"method\", \"faiss\")\n \n if method == \"faiss\":\n return FaissIndex(config)\n elif method == \"annoy\":\n return AnnoyIndex(config)\n elif method == \"hnsw\":\n return HnswlibIndex(config)\n elif method == \"scann\":\n return ScannIndex(config)\n```\n\n资料来源：[src/python/txtai/ann/dense/factory.py:1-40]()\n\n## 支持的后端算法\n\n### 算法对比\n\n| 后端 | 算法类型 | 优点 | 适用场景 | 内存占用 |\n|------|----------|------|----------|----------|\n| Faiss | IVF-PQ, HNSW | Facebook 出品，成熟稳定 | 大规模生产环境 | 中等 |\n| Annoy | 随机投影树 | 内存高效，支持磁盘加载 | 内存受限环境 | 低 |\n| Hnswlib | HNSW | 查询速度快 | 实时搜索 | 较高 |\n| Scann | ScaNN | Google 出品，精度高 | 高精度需求 | 中等 |\n\n### 配置参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `method` | `str` | `\"faiss\"` | 索引方法 |\n| `components` | `dict` | `None` | 后端特定配置 |\n| `path` | `str` | `None` | 索引文件路径 |\n| `dimensions` | `int` | `None` | 向量维度 |\n| `quantization` | `str` | `None` | 量化类型 (PQ, SQ) |\n\n## 工作流程\n\n### 索引构建流程\n\n```mermaid\ngraph TD\n A[输入文档] --> B[向量化处理]\n B --> C[生成向量数组]\n C --> D[IndexFactory.create]\n D --> E{选择后端}\n E -->|Faiss| F[FaissIndex.index]\n E -->|Annoy| G[AnnoyIndex.index]\n E -->|Hnswlib| H[HnswlibIndex.index]\n F --> I[构建倒排文件]\n G --> J[构建随机树]\n H --> K[构建分层图]\n I --> L[保存索引文件]\n J --> L\n K --> L\n```\n\n### 搜索查询流程\n\n```mermaid\ngraph LR\n A[查询向量] --> B[DenseAnn.search]\n B --> C{选择后端}\n C -->|Faiss| D[nprobe 搜索]\n C -->|Annoy| E[树遍历]\n C -->|Hnswlib| F[图遍历]\n D --> G[返回 Top-K 结果]\n E --> G\n F --> G\n```\n\n## 数据模型\n\n### 索引配置结构\n\n```python\n{\n \"method\": \"faiss\",\n \"components\": {\n \"type\": \"IVF\",\n \"nlist\": 100,\n \"pq\": {\n \"m\": 8,\n \"nbits\": 8\n }\n },\n \"path\": \"/path/to/index\",\n \"dimensions\": 768\n}\n```\n\n### 向量存储格式\n\n| 格式 | 后缀 | 说明 |\n|------|------|------|\n| Faiss Binary | `.bin` | 二进制格式索引文件 |\n| Annoy | `.ann` | Annoy 专有格式 |\n| Hnswlib | `.hnsw` | 分层可导航小世界图 |\n| Scann | `.scann` | Google ScaNN 格式 |\n\n## 集成使用\n\n### 基础用法\n\n```python\nfrom txtai.ann import Ann\n\n# 创建 ANN 索引实例\nann = Ann(method=\"faiss\", dimensions=768)\n\n# 构建索引\ndocuments = [\n {\"id\": 1, \"text\": \"示例文本1\", \"vector\": vector1},\n {\"id\": 2, \"text\": \"示例文本2\", \"vector\": vector2}\n]\nann.index(documents)\n\n# 搜索查询\nresults = ann.search(query_vector, limit=10)\n```\n\n### 与 txtai 管道集成\n\ntxtai 的工作管道自动调用 ANN 模块进行索引和搜索，无需直接操作底层 API。\n\n## 扩展机制\n\n### 自定义后端\n\n开发者可以通过继承 `Ann` 基类实现自定义 ANN 后端：\n\n```python\nclass CustomAnn(Ann):\n def __init__(self, path=None, method=None, **kwargs):\n super().__init__(path, method, **kwargs)\n # 初始化自定义索引\n \n def index(self, documents):\n # 实现索引构建逻辑\n pass\n \n def search(self, query, limit=10):\n # 实现搜索逻辑\n pass\n```\n\n### 注册新后端\n\n在 `IndexFactory` 中注册新的后端类型：\n\n```python\nIndexFactory.register(\"custom\", CustomAnn)\n```\n\n## 性能优化建议\n\n### 索引构建优化\n\n1. **批量索引**：使用批量处理减少索引构建时间\n2. **量化压缩**：启用 PQ 或 SQ 量化以减少内存占用\n3. **分区调整**：合理设置 `nlist` 参数平衡精度与性能\n\n### 查询性能优化\n\n1. **nprobe 调优**：Faiss IVF 索引的 `nprobe` 参数直接影响查询精度和速度\n2. **向量归一化**：对查询向量进行 L2 归一化可提高余弦相似度计算精度\n3. **缓存策略**：对于频繁查询的向量实现结果缓存\n\n## 相关资源\n\n- 官方文档：txtai 语义搜索指南\n- 源码仓库：https://github.com/neuml/txtai\n- 问题反馈：GitHub Issues\n\n---\n\n\n\n## 评分系统\n\n### 相关页面\n\n相关主题：[向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/scoring/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/__init__.py)\n- [src/python/txtai/scoring/bm25.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/bm25.py)\n- [src/python/txtai/scoring/tfidf.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/tfidf.py)\n- [src/python/txtai/scoring/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/factory.py)\n \n\n# 评分系统\n\n## 概述\n\n评分系统（Scoring System）是 txtai 框架中用于计算文本相似度和相关性的核心组件。该系统提供了 BM25、TF-IDF 等经典信息检索算法实现，并与向量索引、图网络和关系数据库共同构成了 txtai 的**嵌入数据库（Embeddings Database）**基础架构。\n\ntxtai 的评分系统独立于向量搜索模块，专注于传统信息检索评分方法，为混合搜索场景提供稀疏检索能力。\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 系统架构\n\n### 整体架构\n\n评分系统作为 txtai 的可选扩展模块，位于 `txtai.scoring` 包下，采用模块化工厂模式设计。\n\n```mermaid\ngraph TD\n A[评分系统入口] --> B[工厂类 Factory]\n B --> C[BM25 评分器]\n B --> D[TF-IDF 评分器]\n C --> E[SQLAlchemy 存储]\n D --> E\n F[embeddings 配置] --> B\n```\n\n### 依赖关系\n\n评分系统依赖以下核心库：\n\n| 依赖库 | 版本要求 | 用途 |\n|--------|----------|------|\n| SQLAlchemy | ≥2.0.20 | 数据持久化和存储后端 |\n| NumPy | ≥1.18.4 | 数值计算支持 |\n\n资料来源：[setup.py:55](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 核心组件\n\n### 1. BM25 评分器\n\nBM25（Best Matching 25）是基于概率模型的信息检索评分算法，是 Okapi BM25 的标准实现。该算法克服了传统 TF-IDF 在文档长度归一化方面的不足。\n\n**主要特性：**\n- 可调的词项频率饱和度参数（k1）\n- 可调的文档长度归一化参数（b）\n- 基于 IDF（逆文档频率）的词项权重计算\n\n### 2. TF-IDF 评分器\n\nTF-IDF（Term Frequency-Inverse Document Frequency）是经典的文本向量化与评分方法。该评分器将文本集合转换为稀疏向量表示，支持余弦相似度计算。\n\n**主要特性：**\n- 词频统计与归一化\n- 逆文档频率权重计算\n- 稀疏向量输出格式\n\n### 3. 工厂类\n\n工厂类（Factory）负责根据配置创建和管理评分器实例，支持运行时动态选择评分算法。\n\n资料来源：[src/python/txtai/scoring/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/factory.py)\n\n## 安装配置\n\n### 启用评分系统\n\n通过 pip 安装时指定 scoring 额外依赖：\n\n```bash\npip install txtai[scoring]\n```\n\n此命令将安装核心 txtai 包及评分系统所需的全部依赖。\n\n### setup.py 配置\n\n```python\nextras[\"scoring\"] = [\"sqlalchemy>=2.0.20\"]\n```\n\n资料来源：[setup.py:55](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 与其他模块的集成\n\n### 与 Embeddings 数据库的集成\n\n评分系统是 txtai 嵌入数据库的核心组成部分。根据项目文档，嵌入数据库是以下三者的联合：\n\n```mermaid\ngraph LR\n A[嵌入数据库] --> B[向量索引]\n A --> C[图网络]\n A --> D[关系数据库]\n C --> D\n B --> D\n```\n\n其中，**关系数据库**层集成了评分系统，用于：\n- 存储索引元数据\n- 管理文档映射\n- 执行结构化查询\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 与相似度搜索的集成\n\n评分系统通过 `ann` 和 `vectors` 组合，构成 `similarity` 额外依赖：\n\n```python\nextras[\"similarity\"] = extras[\"ann\"] + extras[\"vectors\"]\n```\n\n这使得 txtai 能够同时支持：\n- **密集向量搜索**：基于 transformer 模型生成的嵌入向量\n- **稀疏评分搜索**：基于 BM25/TF-IDF 的传统信息检索\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 工作流程\n\n### 索引流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[分词处理]\n B --> C[词项统计]\n C --> D[评分计算]\n D --> E[索引存储]\n```\n\n### 搜索流程\n\n```mermaid\ngraph LR\n A[查询语句] --> B[查询处理]\n B --> C[词项匹配]\n C --> D[相关性评分]\n D --> E[结果排序]\n E --> F[返回 Top-K 结果]\n```\n\n## 配置参数\n\n### BM25 配置项\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| k1 | float | 1.5 | 词项频率饱和度参数 |\n| b | float | 0.75 | 文档长度归一化参数 |\n| avgdl | float | 自动计算 | 平均文档长度 |\n\n### TF-IDF 配置项\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| norm | str | \"l2\" | 向量归一化方式（l1/l2/none） |\n| use_idf | bool | True | 是否启用 IDF 权重 |\n| smooth_idf | bool | True | 是否平滑 IDF |\n\n## 应用场景\n\n### 语义与关键词混合搜索\n\n将密集向量搜索与稀疏评分搜索结合，实现更精确的检索结果：\n\n- **向量搜索**：捕获语义相似性\n- **评分搜索**：精确匹配关键词\n\n### 文档排序与重排序\n\n利用 BM25 或 TF-IDF 分数对候选文档进行重排序，提升最终结果的相关性。\n\n### 知识库检索\n\n作为 RAG（检索增强生成）流程中的检索组件，为大语言模型提供高质量的上下文文档。\n\n## 相关源码文件列表\n\n| 文件路径 | 说明 |\n|----------|------|\n| `src/python/txtai/scoring/__init__.py` | 评分系统包入口，定义公共 API |\n| `src/python/txtai/scoring/bm25.py` | BM25 评分算法实现 |\n| `src/python/txtai/scoring/tfidf.py` | TF-IDF 评分算法实现 |\n| `src/python/txtai/scoring/factory.py` | 评分器工厂类，负责实例创建 |\n\n## 扩展与自定义\n\n开发者可通过继承基类实现自定义评分器：\n\n1. 实现评分计算逻辑\n2. 注册到工厂类\n3. 在 embeddings 配置中指定使用\n\n这种设计允许无缝集成第三方评分算法，满足特定业务场景需求。\n\n---\n\n**注意**：本页面基于 txtai 仓库的 setup.py 配置信息和项目文档生成。详细的 API 使用示例请参考官方示例 notebooks。\n\n---\n\n\n\n## LLM管道\n\n### 相关页面\n\n相关主题：[文本处理管道](#page-pipeline-text), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/llm/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/__init__.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/llm/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/factory.py)\n- [src/python/txtai/pipeline/llm/huggingface.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/huggingface.py)\n- [src/python/txtai/pipeline/llm/rag.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/rag.py)\n \n\n# LLM管道\n\n## 概述\n\nLLM管道是txtai框架中负责与大语言模型（Large Language Model）交互的核心组件。该模块封装了多种语言模型的调用方式，提供了统一的接口来执行文本生成、对话、问答等任务。\n\nLLM管道的主要职责包括：\n\n- **统一抽象**：为不同底层的LLM实现提供一致的API接口\n- **生成控制**：支持流式输出、停止词控制、最大长度限制等生成参数\n- **对话支持**：自动处理聊天模板，支持聊天模型和普通语言模型\n- **多模态扩展**：支持视觉语言模型（VLM）的图像处理能力\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[LLM 基类] --> B[HuggingFace 实现]\n A --> C[LiteLLM 实现]\n A --> D[本地 GGML 实现]\n \n E[LLMFactory] -->|创建| A\n \n F[RAG 模块] -->|使用| A\n \n G[Agent 模块] -->|调用| A\n```\n\n### 模块结构\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `llm.py` | LLM基类，定义通用接口和生成逻辑 |\n| `factory.py` | 工厂类，负责根据配置创建LLM实例 |\n| `huggingface.py` | HuggingFace Transformers后端实现 |\n| `rag.py` | RAG增强生成模块 |\n\n## 核心类详解\n\n### LLM基类\n\nLLM类是所有LLM实现的父类，提供了语言模型调用的通用逻辑。\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/llm.py\nclass LLM:\n def __call__(self, text, maxlength=None, stream=False, stop=None, \n defaultrole=\"auto\", stripthink=None, **kwargs):\n # 核心生成方法\n```\n\n#### 方法说明\n\n| 方法 | 返回类型 | 说明 |\n|------|---------|------|\n| `__call__` | 生成内容 | 执行LLM生成的主要接口 |\n| `ischat` | bool | 判断是否为聊天模型 |\n| `isvision` | bool | 判断是否支持视觉任务 |\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `text` | str/list | 必需 | 输入文本，支持字符串或列表 |\n| `maxlength` | int | None | 最大序列长度 |\n| `stream` | bool | False | 是否启用流式输出 |\n| `stop` | list | None | 停止字符串列表 |\n| `defaultrole` | str | \"auto\" | 默认角色（auto/user/prompt） |\n| `stripthink` | bool | None | 是否去除思考标签 |\n\n#### 输入格式支持\n\nLLM管道支持多种输入格式：\n\n1. **字符串或字符串列表**：直接传入文本内容\n2. **字典列表**：遵循聊天模板的role-content格式\n3. **嵌套列表**：二维列表形式的对话历史\n\n```python\n# 示例：不同输入格式\nllm(\"一个简单的问题\") # 字符串\n\nllm([{\"role\": \"user\", \"content\": \"你好\"}]) # 字典列表\n\nllm([[\"user\", \"今天天气如何?\"], [\"assistant\", \"晴天\"]]]) # 嵌套列表\n```\n\n### HuggingFace实现\n\nHuggingFace实现是对Transformers库的直接封装，支持绝大多数HuggingFace模型。\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/huggingface.py\nclass HuggingFace:\n def __call__(self, text, prefix=None, maxlength=512, workers=0, \n stream=False, stop=None, **kwargs):\n```\n\n#### 特殊参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `prefix` | str | None | 添加到文本元素前的前缀 |\n| `workers` | int | 0 | 并发处理的工作线程数 |\n\n#### 任务类型支持\n\nHuggingFace后端支持多种任务类型：\n\n| 任务标识 | 说明 |\n|---------|------|\n| `text2text-generation` | 文本到文本生成（使用SequencesPipeline兼容） |\n| `text-generation` | 标准文本生成 |\n| `summarization` | 摘要生成 |\n| `translation` | 翻译任务 |\n\n## 生成控制\n\n### 流式输出\n\n启用流式输出可以实时获取模型生成的片段：\n\n```python\n# 启用流式输出\nfor chunk in llm(\"写一首诗\", stream=True):\n print(chunk, end=\"\", flush=True)\n```\n\n流式输出会**自动禁用**思考标签去除功能（`stripthink=False`），确保实时显示生成内容。\n\n### 停止词控制\n\n通过`stop`参数可以指定停止条件：\n\n```python\n# 当遇到指定字符串时停止生成\nresult = llm(\"回答以下问题\", stop=[\"\\n\\n\", \"===END===\"])\n```\n\n### 思考标签处理\n\n部分模型会输出XML格式的思考过程，默认行为：\n\n| 模式 | 行为 |\n|------|------|\n| 流式输出（stream=True） | stripthink=False（保留思考内容） |\n| 非流式输出 | stripthink=True（自动去除） |\n\n```python\n# 手动控制思考标签处理\nllm(\"问题\", stripthink=True) # 去除思考标签\nllm(\"问题\", stripthink=False) # 保留思考标签\n```\n\n## RAG增强生成\n\nRAG（检索增强生成）模块将向量检索与LLM生成结合：\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/rag.py\n```\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[用户查询] --> B[向量检索]\n B --> C[相关文档]\n C --> D[构建提示词]\n D --> E[LLM生成]\n E --> F[最终回答]\n```\n\n### 配置示例\n\n```yaml\n# RAG配置示例\nrag:\n embeddings: index.tar\n content: true\n prompt: \"根据以下上下文回答问题：\\n\\n{context}\\n\\n问题：{query}\"\n```\n\n## 工厂模式\n\nLLM工厂类负责根据配置动态创建合适的LLM实例：\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/factory.py\n```\n\n### 支持的后端类型\n\n| 后端标识 | 说明 |\n|---------|------|\n| `huggingface` | HuggingFace Transformers模型 |\n| `litellm` | LiteLLM统一接口 |\n| `ggml` | 本地GGML/GGUF模型 |\n| `ollama` | Ollama本地服务 |\n| `api` | OpenAI兼容API |\n\n## 使用示例\n\n### 基础文本生成\n\n```python\nfrom txtai.pipeline import LLM\n\n# 创建LLM实例\nllm = LLM(\"meta-llama/Llama-2-7b-chat-hf\")\n\n# 简单生成\nresult = llm(\"解释量子计算的基本原理\")\nprint(result)\n```\n\n### 对话模式\n\n```python\n# 带聊天模板的对话\nmessages = [\n {\"role\": \"system\", \"content\": \"你是一个helpful助手\"},\n {\"role\": \"user\", \"content\": \"什么是向量数据库？\"}\n]\n\nresponse = llm(messages)\nprint(response)\n```\n\n### 带RAG的问答\n\n```python\nfrom txtai.pipeline import RAG\n\n# 创建RAG管道\nrag = RAG({\n \"embeddings\": \"my-index\",\n \"llm\": \"mistralai/Mistral-7B-Instruct-v0.2\"\n})\n\n# 基于检索的问答\nanswer = rag(\"关于项目X的技术细节是什么？\")\n```\n\n## 依赖要求\n\nLLM管道的基础依赖包括：\n\n```python\n# setup.py中的pipeline-llm额外依赖\nextras[\"pipeline-llm\"] = [\n \"httpx>=0.28.1\",\n \"litellm>=1.37.16\",\n \"llama-cpp-python>=0.2.75\"\n]\n```\n\n安装完整LLM支持：\n\n```bash\npip install txtai[pipeline-llm]\n```\n\n## 最佳实践\n\n1. **模型选择**：根据硬件条件选择合适的模型量级\n2. **批处理**：处理大量文本时使用workers参数启用并行\n3. **流式输出**：长文本生成建议启用流式以便及时中断\n4. **停止词**：设置合理的停止条件以控制输出长度\n5. **错误处理**：实现重试机制应对API临时故障\n\n## 相关资源\n\n- [txtai官方文档](https://neuml.github.io/txtai/)\n- [示例笔记本](https://neuml.github.io/txtai/examples)\n- [GitHub仓库](https://github.com/neuml/txtai)\n\n---\n\n\n\n## 文本处理管道\n\n### 相关页面\n\n相关主题：[LLM管道](#page-pipeline-llm), [音频和图像管道](#page-pipeline-audio), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/text/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/__init__.py)\n- [src/python/txtai/pipeline/text/entity.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/entity.py)\n- [src/python/txtai/pipeline/text/labels.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/labels.py)\n- [src/python/txtai/pipeline/text/reranker.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/reranker.py)\n- [src/python/txtai/pipeline/text/summary.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/summary.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n \n\n# 文本处理管道\n\n文本处理管道（Text Pipeline）是txtai框架中用于处理和分析文本数据的核心组件集合。该管道提供了从文本生成摘要、实体识别、标签分类到结果重排序等完整的自然语言处理能力。\n\n## 概述\n\ntxtai的文本处理管道是一组基于Transformer模型的处理组件，设计用于执行各类文本分析任务。这些管道可以独立使用，也可以组合成复杂的工作流程来处理文本数据。文本处理管道属于txtai的`pipeline-text`扩展模块，需要额外安装相关依赖。\n\n```mermaid\ngraph TD\n A[文本输入] --> B[Summary 摘要生成]\n A --> C[Entity 实体识别]\n A --> D[Labels 标签分类]\n A --> E[Reranker 重排序]\n B --> F[结构化输出]\n C --> F\n D --> F\n E --> G[排序后结果]\n```\n\n## 核心组件\n\n文本处理管道包含以下核心组件：\n\n| 组件名称 | 类名 | 功能描述 |\n|---------|------|---------|\n| 摘要生成 | `Summary` | 从文本生成简洁摘要 |\n| 实体识别 | `Entity` | 识别文本中的命名实体 |\n| 标签分类 | `Labels` | 对文本进行标签分类 |\n| 重排序 | `Reranker` | 对搜索结果进行相关性重排序 |\n\n## 摘要生成（Summary）\n\n### 功能说明\n\n摘要生成管道使用预训练的序列到序列模型将长文本压缩为简洁的摘要内容。该组件支持多种输入格式，可以处理单个文档或批量处理多个文档。\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 模型路径或HuggingFace模型标识符 |\n| `quantize` | bool | False | 是否量化模型 |\n| `gpu` | bool | True | 是否使用GPU |\n| `maxlength` | int | 512 | 生成摘要的最大长度 |\n| `workers` | int | 0 | 并发工作线程数 |\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Summary\n\n# 初始化摘要管道\nsummary = Summary(\"facebook/bart-large-cnn\")\n\n# 生成摘要\ntext = \"\"\"长文本内容...\"\"\"\nresult = summary(text)\n```\n\n资料来源：[src/python/txtai/pipeline/text/summary.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/summary.py)\n\n## 实体识别（Entity）\n\n### 功能说明\n\n实体识别管道用于从文本中提取命名实体及其类型标签。该组件支持两种模式：标准token分类和GLiNER模型。\n\n### GLiNER支持\n\n当检测到使用GLiNER模型时，管道会使用GLiNER库进行实体识别，这提供了更加灵活和高效的实体提取能力。\n\n```python\n# GLiNER实体识别示例\nentity = Entity(\"urchan/gliner_multitask_large-v0.1\")\nentities = entity(\"Apple公司成立于1976年\", labels=[\"组织\", \"日期\"])\n```\n\n### 聚合方法\n\n实体识别支持多种聚合策略来合并多token实体：\n\n| 聚合方法 | 说明 |\n|---------|------|\n| `simple` | 简单合并（默认） |\n| `first` | 取第一个token的分数 |\n| `average` | 取平均分数 |\n| `max` | 取最大分数 |\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 模型路径 |\n| `labels` | list | None | 要识别的实体类型列表 |\n| `aggregate` | str | \"simple\" | 多token实体聚合方法 |\n| `flatten` | bool/float | None | 展平输出，可设置分数阈值 |\n| `join` | bool | False | 是否连接相邻同类型实体 |\n| `workers` | int | 0 | 并发工作线程数 |\n\n资料来源：[src/python/txtai/pipeline/text/entity.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/entity.py)\n\n## 标签分类（Labels）\n\n### 功能说明\n\n标签分类管道用于对文本进行分类标签预测。该组件可以将文本分类为一个或多个预定义的类别标签。\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Labels\n\n# 初始化标签分类器\nlabels = Labels()\n\n# 单标签分类\nresult = labels(\"这部电影非常精彩\", labels=[\"正面\", \"负面\", \"中性\"])\n\n# 多标签分类\nmultilabel = labels(\"新闻内容\", labels=[\"体育\", \"科技\", \"娱乐\"], multi=True)\n```\n\n### 分数阈值\n\n标签分类支持设置分数阈值来过滤低置信度的分类结果：\n\n```python\n# 只返回分数大于0.8的结果\nresult = labels(text, labels=labels_list, threshold=0.8)\n```\n\n资料来源：[src/python/txtai/pipeline/text/labels.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/labels.py)\n\n## 重排序（Reranker）\n\n### 功能说明\n\n重排序管道用于对搜索结果进行相关性重排序。当基础的向量相似度搜索无法完全满足相关性需求时，可以使用重排序模型进行更精确的排序。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[初始搜索结果] --> B[Reranker模型]\n B --> C[相关性评分]\n C --> D[重排序后的结果]\n```\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Reranker\n\n# 初始化重排序模型\nreranker = Reranker(\"cross-encoder/ms-marco-MiniLM-L-6-v2\")\n\n# 对搜索结果进行重排序\nquery = \"人工智能应用\"\nresults = [{\"id\": 1, \"text\": \"机器学习技术\"}, {\"id\": 2, \"text\": \"人工智能算法\"}]\nreranked = reranker(query, results)\n```\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 重排序模型路径 |\n| `gpu` | bool | True | 是否使用GPU |\n| `batchsize` | int | 32 | 批处理大小 |\n| `quantize` | bool | False | 是否量化模型 |\n\n资料来源：[src/python/txtai/pipeline/text/reranker.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/reranker.py)\n\n## 管道组合使用\n\n文本处理管道可以组合使用以构建复杂的文本分析流程：\n\n```mermaid\ngraph TD\n A[原始文本] --> B[Textractor 文本提取]\n B --> C[Entity 实体识别]\n B --> D[Labels 标签分类]\n C --> E[Summary 摘要生成]\n D --> F[结果合并]\n E --> F\n F --> G[最终输出]\n```\n\n### 工作流集成\n\n在txtai工作流中，文本处理管道可以作为任务节点使用：\n\n```python\nfrom txtai.workflow import Workflow\n\n# 定义工作流\nworkflow = Workflow([\n Textractor(),\n Summary(),\n # 更多处理步骤...\n])\n```\n\n## 依赖项\n\n文本处理管道模块需要以下依赖项：\n\n| 依赖包 | 版本要求 | 说明 |\n|-------|---------|------|\n| gliner | >=0.2.23 | GLiNER实体识别模型 |\n| sentencepiece | >=0.1.91 | 分词工具 |\n| staticvectors | >=0.2.0 | 静态向量模型 |\n| transformers | >=4.56.2 | 核心Transformer库 |\n\n安装所有文本处理依赖：\n\n```bash\npip install txtai[pipeline-text]\n```\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 输入输出格式\n\n### 标准输入格式\n\n文本处理管道支持多种输入格式：\n\n| 格式类型 | 示例 | 说明 |\n|---------|------|------|\n| 字符串 | `\"文本内容\"` | 单个文本 |\n| 字符串列表 | `[\"文本1\", \"文本2\"]` | 批量文本 |\n| 字典列表 | `[{\"text\": \"...\"}]` | 带元数据的文本 |\n\n### 输出格式\n\n处理结果通常以列表或字典格式返回：\n\n```python\n# 实体识别输出示例\n[\n {\"text\": \"Apple\", \"label\": \"组织\", \"score\": 0.95, \"start\": 0, \"end\": 5},\n {\"text\": \"1976年\", \"label\": \"日期\", \"score\": 0.89, \"start\": 15, \"end\": 20}\n]\n\n# 标签分类输出示例\n[(\"正面\", 0.92), (\"中性\", 0.06), (\"负面\", 0.02)]\n```\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量处理**：使用批量输入可以显著提高处理速度\n2. **GPU加速**：确保CUDA环境正确配置以启用GPU加速\n3. **模型量化**：对于大模型，使用量化可以减少内存占用\n\n### 准确性提升\n\n1. 选择与任务领域匹配的专业模型\n2. 合理设置标签列表和分数阈值\n3. 结合多种管道组件进行综合分析\n\n### 错误处理\n\n```python\ntry:\n result = pipeline(input_text)\nexcept Exception as e:\n logger.error(f\"处理失败: {e}\")\n # 降级处理或返回默认值\n```\n\n## 扩展文本管道\n\n开发者可以通过继承基础管道类来创建自定义文本处理组件：\n\n```python\nfrom txtai.pipeline import HFPipeline\n\nclass CustomTextProcessor(HFPipeline):\n def __init__(self, path=None, quantize=False, gpu=True, **kwargs):\n super().__init__(\"text-classification\", path, quantize, gpu, **kwargs)\n \n def __call__(self, text, **kwargs):\n # 自定义处理逻辑\n return super().__call__(text, **kwargs)\n```\n\n资料来源：[src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n\n---\n\n\n\n## 音频和图像管道\n\n### 相关页面\n\n相关主题：[文本处理管道](#page-pipeline-text), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/audio/transcription.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/audio/transcription.py)\n- [src/python/txtai/pipeline/audio/texttoaudio.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/audio/texttoaudio.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/pipeline/image/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/image/__init__.py)\n- [src/python/txtai/pipeline/image/caption.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/image/caption.py)\n- [src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n \n\n# 音频和图像管道\n\n## 概述\n\ntxtai 的音频和图像管道是框架多媒体处理能力的核心组成部分，分别位于 `txtai.pipeline.audio` 和 `txtai.pipeline.image` 模块中。这些管道支持从音频文件中提取文本内容（语音转文本），以及从文本生成音频（文本转语音）和图像描述（图像字幕生成）。\n\n音频管道基于 Hugging Face Transformers 框架构建，通过 `HFPipeline` 基类提供统一的接口。图像管道同样继承自 `HFPipeline`，使用计算机视觉模型处理图像数据。两者都支持 GPU 加速和模型量化，能够处理单个文件或批量数据。\n\n## 音频管道\n\n### 架构设计\n\n音频管道采用模块化设计，主要包含两个核心组件：\n\n```mermaid\ngraph TD\n A[音频输入] --> B{数据类型判断}\n B -->|文件路径| C[FileToHTML/直接加载]\n B -->|原始音频数据| D[Signal处理模块]\n C --> E[Transcription管道]\n D --> E\n E --> F[Speech Recognition Pipeline]\n F --> G[转录文本输出]\n```\n\n### Transcription 模块\n\n`Transcription` 类负责将音频内容转录为文本。该模块支持两种后端实现：当 `scipy` 和 `soundfile` 库可用时，使用本地信号处理；否则回退到其他可用方案。资料来源：[transcription.py:1-20]()\n\n```python\nclass Transcription(HFPipeline):\n \"\"\"\n Transcribes audio files or data to text.\n \"\"\"\n```\n\n#### 核心参数说明\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| path | str | 模型路径或 Hugging Face 模型标识符 | None |\n| quantize | bool | 是否量化模型以减少内存占用 | False |\n| gpu | bool | 是否使用 GPU 进行推理 | True |\n| model | str | 指定具体模型变体 | None |\n\n#### 主要方法\n\n`__call__(audio, rate=None, chunk=10, join=True, **kwargs)` 方法是 Transcription 的核心接口：\n\n```python\ndef __call__(self, audio, rate=None, chunk=10, join=True, **kwargs):\n \"\"\"\n Transcribes audio files or data to text.\n\n Args:\n audio: audio|list\n rate: sample rate, only required with raw audio data\n chunk: process audio in chunk second sized segments\n join: if True (default), combine each chunk back together into a single text output.\n When False, chunks are returned as a list of dicts, each having raw associated audio and\n sample rate in addition to text\n \"\"\"\n```\n\n该方法支持三种处理模式：\n\n- **完整转录**：设置 `chunk=0` 可对整个音频文件进行一次性处理\n- **分段转录**：设置 `chunk` 值（秒）可按指定时长分段处理长音频\n- **批量转录**：传入音频列表可并行处理多个文件\n\n#### 输入输出格式\n\n| 输入类型 | 输入示例 | 输出类型 | 输出示例 |\n|----------|----------|----------|----------|\n| 单个音频文件路径 | `\"/path/to/audio.wav\"` | str | `\"转录的文本内容\"` |\n| 音频文件列表 | `[\"file1.wav\", \"file2.wav\"]` | list | `[\"文本1\", \"文本2\"]` |\n| 原始音频数据 | `(numpy数组, 采样率)` | str/list | 根据输入格式确定 |\n\n### TextToAudio 模块\n\n`TextToAudio` 类执行相反的操作，将文本内容转换为语音音频。该模块继承自 `HFPipeline`，使用 text-to-speech 模型生成音频波形。资料来源：[texttoaudio.py:1-30]()\n\n```python\nclass TextToAudio(HFPipeline):\n \"\"\"\n Generates audio from text.\n \"\"\"\n```\n\n#### 参数配置\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| path | str | TTS 模型路径 | None |\n| quantize | bool | 量化模型 | False |\n| gpu | bool | GPU 加速 | True |\n| model | str | 模型标识符 | None |\n| rate | int | 目标采样率 | None（使用模型默认采样率） |\n\n#### 工作流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[TextToAudio Pipeline]\n B --> C[generate audio]\n C --> D{rate 参数设置?}\n D -->|是| E[重采样到目标采样率]\n D -->|否| F[使用模型原生采样率]\n E --> G[(音频输出)]\n F --> G\n```\n\n#### 音频转换处理\n\n当设置 `rate` 参数时，`convert` 方法会执行采样率转换：\n\n```python\ndef convert(self, result):\n \"\"\"\n Converts audio result to target sample rate for this pipeline, if set.\n\n Args:\n result: dict with audio samples and sample rate\n\n Returns:\n audio with converted sample rate\n \"\"\"\n```\n\n返回格式为元组 `(audio_data, sample_rate)`，可直接用于音频播放或保存。\n\n## 图像管道\n\n### ImageCaption 模块\n\n`ImageCaption` 类使用计算机视觉模型为图像生成描述性文本。该模块同样继承自 `HFPipeline`，使用图像字幕生成模型。资料来源：[caption.py]()\n\n```python\nclass ImageCaption(HFPipeline):\n \"\"\"\n Image captioning pipeline that generates descriptions for images.\n \"\"\"\n```\n\n### 图像处理流程\n\n```mermaid\ngraph TD\n A[图像输入] --> B{输入类型判断}\n B -->|URL| C[HTTP 请求获取]\n B -->|文件路径| D[本地文件读取]\n B -->|PIL Image| E[直接处理]\n B -->|Base64| F[解码处理]\n C --> G[图像预处理]\n D --> G\n E --> G\n F --> G\n G --> H[Vision Transformer 模型]\n H --> I[生成字幕/描述]\n I --> J[文本输出]\n```\n\n## 统一 API 接口\n\n所有管道都遵循统一的调用约定，简化了多模态处理的复杂性：\n\n### HFPipeline 基类\n\n音频和图像管道都继承自 `HFPipeline` 基类，该基类提供：\n\n- 统一的模型加载和缓存机制\n- GPU/CPU 自动检测和设备分配\n- 批量处理支持\n- 流式输出支持（部分管道）\n\n### 通用参数\n\n| 参数 | 说明 | 适用管道 |\n|------|------|----------|\n| path | 模型路径或 Hugging Face 模型 ID | 所有管道 |\n| quantize | 启用 4-bit/8-bit 量化 | 所有管道 |\n| gpu | 启用 GPU 推理 | 所有管道 |\n| model | 指定具体模型配置 | 所有管道 |\n\n## 依赖要求\n\n音频和图像管道需要安装特定的依赖包。通过 `pipeline-audio` 和 `pipeline-image` extras 可一键安装：\n\n```bash\npip install txtai[pipeline-audio]\npip install txtai[pipeline-image]\n```\n\n### 音频管道依赖\n\n根据 `setup.py` 配置：\n\n```python\nextras[\"pipeline-audio\"] = [\n \"onnx>=1.11.0\",\n \"onnxruntime>=1.11.0\",\n \"scipy>=1.4.1\",\n \"sounddevice>=0.5.0\",\n \"soundfile>=0.10.3.post1\",\n \"ttstokenizer>=1.1.0\",\n \"webrtcvad-wheels>=2.0.14\",\n]\n```\n\n### 图像管道依赖\n\n```python\nextras[\"pipeline-image\"] = [\n \"imagehash>=4.2.1\",\n \"pillow>=7.1.2\",\n \"timm>=0.4.12\",\n]\n```\n\n## 实际应用示例\n\n### 音频转录\n\n```python\nfrom txtai.pipeline import Transcription\n\n# 初始化转录管道\ntranscribe = Transcription(\"facebook/wav2vec2-base-960h\")\n\n# 单个文件转录\ntext = transcribe(\"/path/to/audio.wav\")\n\n# 分段处理长音频（每段30秒）\ntext = transcribe(\"/path/to/long_audio.wav\", chunk=30)\n\n# 批量处理\ntexts = transcribe([\"file1.wav\", \"file2.wav\"])\n```\n\n### 文本转语音\n\n```python\nfrom txtai.pipeline.audio import TextToAudio\n\n# 初始化 TTS 管道\ntts = TextToAudio(\"facebook/fastspeech2-en-ljspeech\")\n\n# 生成音频\naudio, rate = tts(\"Hello, this is a text to speech conversion.\")\n\n# 指定采样率\naudio, rate = tts(\"Custom sample rate audio\", rate=22050)\n```\n\n## 工作流集成\n\n音频和图像管道可以无缝集成到 txtai 的工作流系统中，支持复杂的多模态处理流程：\n\n```python\nfrom txtai import Workflow\n\n# 创建包含音频处理的工作流\nworkflow = Workflow([\n {\"action\": \"transcription\", \"task\": \"audio\"},\n {\"action\": \"translation\", \"task\": \"text\"},\n])\n```\n\n## 最佳实践\n\n1. **模型选择**：根据精度和速度需求选择合适的预训练模型\n2. **GPU 加速**：处理大量数据时启用 GPU 以提升性能\n3. **批量处理**：使用列表输入进行批量处理，提高吞吐量\n4. **内存管理**：长音频文件使用分段处理避免内存溢出\n5. **采样率配置**：确保输出音频采样率符合目标应用需求\n\n## 总结\n\ntxtai 的音频和图像管道提供了强大且统一的多媒体处理能力。通过继承 `HFPipeline` 基类，这些管道实现了标准化的接口和一致的配置方式。Transcription 支持灵活的音频转文本处理，TextToAudio 提供文本到语音的生成能力，ImageCaption 则实现图像描述生成。这些组件可以独立使用，也可以集成到更复杂的工作流中，支持端到端的多模态 AI 应用开发。\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[核心组件](#page-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/workflow/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/__init__.py)\n- [src/python/txtai/workflow/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/base.py)\n- [src/python/txtai/workflow/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/factory.py)\n- [src/python/txtai/workflow/task/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/__init__.py)\n \n\n# 工作流引擎\n\n## 概述\n\ntxtai 工作流引擎是一个强大的组件编排框架，用于构建复杂的数据处理管道。它允许用户将多个处理组件（如文本提取、摘要生成、翻译等）串联成可配置的工作流程，支持并行处理、并发执行、结果合并等高级功能。\n\n工作流引擎的核心设计理念是**声明式任务编排**：用户通过定义任务列表来描述数据处理流程，系统自动管理任务间的数据传递和执行顺序。\n\n## 核心架构\n\n### 组件层次结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Workflow │\n│ ┌───────────────────────────────────────────────────────┐ │\n│ │ Task[] │ │\n│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │\n│ │ │ Task 1 │→ │ Task 2 │→ │ Task 3 │→ │ Task N │ │ │\n│ │ │(动作函数)│ │(动作函数)│ │(动作函数)│ │(动作函数)│ │ │\n│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │\n│ └───────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ ┌───────────────────────────────────────────────────────┐ │\n│ │ 任务基类 (Task Base) │ │\n│ │ - action: 处理动作 │ │\n│ │ - select: 数据过滤器 │ │\n│ │ - initialize/finalize: 生命周期钩子 │ │\n│ └───────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心类说明\n\n| 类名 | 文件位置 | 功能描述 |\n|------|----------|----------|\n| Workflow | workflow/__init__.py | 工作流主控制器，管理任务执行流程 |\n| Task | workflow/task/base.py | 任务基类，定义任务通用接口 |\n| TemplateTask | workflow/task/template.py | 模板任务，支持 prompt 模板化处理 |\n\n## 工作流执行模型\n\n### 数据处理流程\n\n```mermaid\ngraph LR\n A[输入数据] --> B[Task 1]\n B --> C[Task 2]\n C --> D[Task 3]\n D --> E[输出结果]\n \n F[初始化动作] -.-> A\n E -.-> G[最终化动作]\n```\n\n### 并发处理模型\n\n```mermaid\ngraph TD\n subgraph 并发模式\n A[输入列表] --> B{并发方式}\n B -->|Thread| C[线程池执行]\n B -->|Process| D[进程池执行]\n B -->|默认| E[顺序执行]\n end\n \n C --> F[结果聚合]\n D --> F\n E --> F\n```\n\n## Task 基类详解\n\n### 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| action | callable/list | [] | 要执行的处理动作 |\n| select | callable/list | None | 数据过滤选择器 |\n| unpack | bool | True | 是否解包数据元组 |\n| column | int | None | 选择元组的列索引 |\n| merge | str | \"hstack\" | 多动作输出合并模式 |\n| initialize | callable | None | 执行前初始化动作 |\n| finalize | callable | None | 执行后终结动作 |\n| concurrency | str | None | 并发方式 (\"thread\"/\"process\") |\n| onetomany | bool | True | 启用一对多转换 |\n\n### 核心方法\n\n```python\ndef __init__(\n self,\n action=None,\n select=None,\n unpack=True,\n column=None,\n merge=\"hstack\",\n initialize=None,\n finalize=None,\n concurrency=None,\n onetomany=True,\n **kwargs,\n)\n```\n\n**生命周期钩子**：\n\n- **initialize**: 在处理开始前执行，常用于加载模型、资源初始化\n- **finalize**: 在处理结束后执行，常用于资源释放、结果后处理\n\n资料来源：[src/python/txtai/workflow/task/base.py:22-50]()\n\n## 模板任务 (TemplateTask)\n\nTemplateTask 继承自 Task 基类，专门用于生成 LLM 提示词模板。\n\n### 模板处理规则\n\n```mermaid\ngraph TD\n A[输入数据] --> B{数据类型判断}\n B -->|dict| C[作为命名参数传入]\n B -->|tuple| D[映射为 arg0-argN]\n B -->|其他| E[作为 {text} 参数]\n \n C --> F[TemplateFormatter 格式化]\n D --> F\n E --> F\n F --> G[渲染后的模板字符串]\n```\n\n### 模板注册方法\n\n```python\ndef register(self, template=None, rules=None, strict=True):\n # template: 提示词模板文本\n # rules: 参数处理规则\n # strict: 是否要求所有输入被模板消费\n```\n\n支持的模板参数注入方式：\n\n| 输入类型 | 处理方式 | 示例 |\n|----------|----------|------|\n| dict | 展开为命名参数 | `{\"topic\": \"AI\", \"length\": 100}` |\n| tuple | 映射为 arg0-argN | `(\"AI\", 100)` → arg0=\"AI\", arg1=100 |\n| 其他 | 作为 {text} 参数 | `input` → {text}=input |\n\n资料来源：[src/python/txtai/workflow/task/template.py:10-45]()\n\n## 工作流构建示例\n\n### 基础使用模式\n\n```python\nfrom txtai import Workflow\nfrom txtai.pipeline import Summary, Textractor, Translation\nfrom txtai.workflow import Task\n\n# 步骤1: 定义处理管道\ntextractor = Textractor(backend=\"docling\", headers={\"user-agent\": \"Mozilla/5.0\"})\nsummary = Summary()\ntranslate = Translation()\n\n# 步骤2: 构建工作流\nworkflow = Workflow([\n Task(textractor), # 提取文本\n Task(summary), # 生成摘要\n Task(lambda inputs: [translate(x, \"fr\") for x in inputs]) # 翻译\n])\n\n# 步骤3: 执行工作流\nresults = list(workflow([\"https://example.com/article\"]))\n```\n\n### 使用 LLM 完成任务\n\n```python\nfrom txtai import LLM, Workflow\nfrom txtai.pipeline import Textractor\nfrom txtai.workflow import Task\n\ntextractor = Textractor(backend=\"docling\")\nllm = LLM(\"Qwen/Qwen3-4B-Instruct\")\n\nworkflow = Workflow([\n Task(textractor),\n Task(lambda inputs: llm([f\"Summarize in 40 words: {x}\" for x in inputs]))\n])\n\nlist(workflow([\"https://example.com\"]))\n```\n\n资料来源：[examples/workflow_quickstart.py:1-45]()\n\n## 内置任务类型\n\n### UrlTask\n\n专门用于处理 URL 链接的预配置任务，自动调用 Textractor 进行内容提取。\n\n```python\nfrom txtai.workflow import UrlTask, Task, Workflow\nfrom txtai.pipeline import Textractor, Summary\n\nworkflow = Workflow([\n UrlTask(Textractor(paragraphs=True, minlength=100, join=True)),\n Task(Summary(\"sshleifer/distilbart-cnn-12-6\"))\n])\n\n# 处理 URL\nurl = \"https://neuml.com\"\nsummary = list(workflow([url]))[0]\n```\n\n### 任务组合模式\n\n| 组合方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| 顺序执行 | 任务列表按顺序传递 | 管道式处理 |\n| 并行执行 | concurrency=\"thread\"/\"process\" | CPU/IO 密集型任务 |\n| 一对多 | onetomany=True | 数据分割/扩展 |\n\n资料来源：[examples/article.py:1-55]()\n\n## 工作流配置\n\n### 依赖项配置\n\n工作流引擎通过 setup.py 管理可选依赖：\n\n```python\nextras[\"workflow\"] = [\n \"apache-libcloud>=3.3.1\",\n \"croniter>=1.2.0\",\n \"openpyxl>=3.0.9\",\n \"pandas>=1.1.0\",\n \"pillow>=7.1.2\",\n \"requests>=2.26.0\",\n \"xmltodict>=0.12.0\",\n]\n```\n\n### 安装方式\n\n```bash\n# 基础安装\npip install txtai\n\n# 包含工作流依赖\npip install txtai[workflow]\n```\n\n## 高级特性\n\n### 数据选择与过滤\n\n```python\n# 使用 select 参数过滤数据\nworkflow = Workflow([\n Task(action=processor, select=lambda x: x.get(\"valid\")),\n])\n```\n\n### 结果合并策略\n\n| 合并模式 | 说明 |\n|----------|------|\n| hstack | 水平堆叠（默认） |\n| 自定义 | 通过 merge 参数指定合并函数 |\n\n### 生命周期管理\n\n```python\ndef init_model():\n \"\"\"初始化动作 - 加载模型\"\"\"\n return load_heavy_model()\n\ndef cleanup(results):\n \"\"\"终结动作 - 清理资源\"\"\"\n return post_process(results)\n\nworkflow = Workflow([\n Task(action=process, initialize=init_model, finalize=cleanup)\n])\n```\n\n## 最佳实践\n\n### 性能优化建议\n\n1. **合理选择并发模式**：CPU 密集型用 \"process\"，IO 密集型用 \"thread\"\n2. **减少不必要的数据转换**：使用 unpack=False 保持数据格式\n3. **使用缓存**：对于重复执行的工作流，考虑缓存模型加载\n\n### 错误处理\n\n```python\nworkflow = Workflow([\n Task(action=risky_processor),\n Task(action=fallback_processor), # 异常时使用后备方案\n])\n```\n\n### 与 LLM 集成\n\n工作流引擎是构建 RAG（检索增强生成）管道的基础组件：\n\n```mermaid\ngraph LR\n A[文档] --> B[Textractor]\n B --> C[分割器]\n C --> D[Embedding]\n D --> E[(向量数据库)]\n E --> F[检索]\n F --> G[LLM 生成]\n```\n\n## 总结\n\ntxtai 工作流引擎提供了灵活、高效的组件编排能力，其核心特点包括：\n\n- **声明式配置**：通过任务列表声明处理流程\n- **丰富的数据转换**：支持多种数据格式和合并策略\n- **生命周期管理**：initialize/finalize 钩子支持资源管理\n- **并发执行**：支持线程和进程两种并发模式\n- **与 LLM 深度集成**：可无缝连接语言模型处理\n\n工作流引擎是构建复杂 AI 应用的核心基础设施，特别适用于文档处理管道、RAG 系统和多阶段数据处理场景。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：neuml/txtai\n\n摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add `txtai_minimal` package。\n\n## 1. 安装坑 · 来源证据：Add `txtai_minimal` package\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add `txtai_minimal` package\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e4050b59fdf4d51ac21e82d248e589e | https://github.com/neuml/txtai/issues/1090 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Add custom Captions implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Captions implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff6fe05065564e85a549d7656b85a852 | https://github.com/neuml/txtai/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Add custom Questions pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Questions pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa68ea29089d497bb8278c3c360c363c | https://github.com/neuml/txtai/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Add custom Sequences pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Sequences pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0099afb385ef498d8020521bbf3e9e64 | https://github.com/neuml/txtai/issues/1086 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Add custom Summary pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Summary pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d8f75c31fc6450d8659b310f25d0bf4 | https://github.com/neuml/txtai/issues/1085 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Add minimal Docker build script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add minimal Docker build script\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38e1e56a991b412bbc749d2c0b687d54 | https://github.com/neuml/txtai/issues/1092 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Make `transformers` package optional for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Make `transformers` package optional for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d755829200de4d93b2f4d2f71b36aaf1 | https://github.com/neuml/txtai/issues/1091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Reduce dependencies to just `numpy` for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Reduce dependencies to just `numpy` for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_395b735968ab4ec8ad849070d43cd18f | https://github.com/neuml/txtai/issues/1093 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：Support minimal install for edge devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support minimal install for edge devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec8e039baf4412888ed3ac543ea1361 | https://github.com/neuml/txtai/issues/1089 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Various training pipeline fixes for v5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Various training pipeline fixes for v5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b47325d7496248a993d980c3d59f3269 | https://github.com/neuml/txtai/issues/1088 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：Zero dependency minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Zero dependency minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7839a465e7e64f94acfff001c1da978c | https://github.com/neuml/txtai/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v9.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v9.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b842ce68a1c4c1ab0a40a3ed1fd213c | https://github.com/neuml/txtai/releases/tag/v9.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:286301447 | https://github.com/neuml/txtai | README/documentation is current enough for a first validation pass.\n\n## 14. 运行坑 · 来源证据：v9.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v9.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3f61e41f6e84b9b9ee33d5e18dbff63 | https://github.com/neuml/txtai/releases/tag/v9.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：Add LiteRT-LM LLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add LiteRT-LM LLM\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8731971fd8404df082f75ecf565fef8b | https://github.com/neuml/txtai/issues/1095 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v9.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.6.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe429d6152304930bda149c4fbd35318 | https://github.com/neuml/txtai/releases/tag/v9.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v9.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bebd6701b454baaae22d73522ce9704 | https://github.com/neuml/txtai/releases/tag/v9.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | release_recency=unknown\n\n\n",
"markdown_key": "txtai",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:286301447",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/neuml/txtai"
},
{
"evidence_id": "art_aa63afbfafb94c67827adad079c717f2",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/neuml/txtai#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "txtai 说明书",
"toc": [
"https://github.com/neuml/txtai 项目说明书",
"目录",
"txtai概述",
"1. 项目简介",
"2. 核心功能特性",
"3. 系统架构",
"4. 依赖体系",
"5. 主要组件详解",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "57de5b3a94e888219d543e84fe4b0abdaed94c28",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"docs/further.md",
"docs/why.md",
"docs/index.md",
"docs/usecases.md",
"docs/install.md",
"docs/poweredby.md",
"docs/examples.md",
"docs/cloud.md",
"docs/faq.md",
"docs/models.md",
"docs/observability.md",
"docs/api/customization.md",
"docs/api/security.md",
"docs/api/index.md",
"docs/api/configuration.md",
"docs/api/methods.md",
"docs/api/mcp.md",
"docs/api/openai.md",
"docs/api/cluster.md",
"docs/embeddings/index.md",
"docs/embeddings/indexing.md",
"docs/embeddings/format.md",
"docs/embeddings/methods.md",
"docs/embeddings/query.md",
"docs/workflow/schedule.md",
"docs/workflow/index.md",
"docs/pipeline/index.md",
"docs/agent/index.md",
"docs/agent/configuration.md",
"docs/agent/methods.md",
"docs/embeddings/configuration/scoring.md",
"docs/embeddings/configuration/index.md",
"docs/embeddings/configuration/ann.md",
"docs/embeddings/configuration/database.md",
"docs/embeddings/configuration/cloud.md",
"docs/embeddings/configuration/graph.md",
"docs/embeddings/configuration/vectors.md",
"docs/embeddings/configuration/general.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# txtai - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 txtai 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/install.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `curl -X GET \"http://localhost:8000/search?query=positive\"` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install txtai` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等\n- `pip install txtai[all]` 证据：`docs/install.md` Claim：`clm_0006` supported 0.86\n- `pip install txtai[ann]` 证据：`docs/install.md` Claim：`clm_0007` supported 0.86\n- `pip install txtai[api]` 证据：`docs/install.md` Claim：`clm_0008` supported 0.86\n- `pip install txtai[cloud]` 证据：`docs/install.md` Claim：`clm_0009` supported 0.86\n- `pip install txtai[console]` 证据：`docs/install.md` Claim：`clm_0010` supported 0.86\n- `pip install txtai[database]` 证据：`docs/install.md` Claim：`clm_0011` supported 0.86\n- `pip install txtai[graph]` 证据：`docs/install.md` Claim：`clm_0012` supported 0.86\n- `pip install txtai[model]` 证据：`docs/install.md` Claim：`clm_0013` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/install.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/install.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/install.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0023` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/install.md` Claim：`clm_0024` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/install.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：567\n- 重要文件覆盖：40/567\n- 证据索引条目：80\n- 角色 / Skill 条目：76\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 txtai 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 txtai 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 txtai 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 76 个角色 / Skill / 项目文档条目。\n\n- **Installation**（project_doc）：! install images/install.png only-light ! install images/install-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/install.md`\n- **Why txtai?**（project_doc）：txtai is an all-in-one AI framework for semantic search, LLM orchestration and language model workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Cloud**（project_doc）：! cloud images/cloud.png only-light ! cloud images/cloud-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cloud.md`\n- **Examples**（project_doc）：! examples images/examples.png only-light ! examples images/examples-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/examples.md`\n- **FAQ**（project_doc）：Below is a list of frequently asked questions and common issues encountered. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/faq.md`\n- **Further reading**（project_doc）：! further images/further.png only-light ! further images/further-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/further.md`\n- **Index**（project_doc）：txtai is an all-in-one AI framework for semantic search, LLM orchestration and language model workflows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Model guide**（project_doc）：See the table below for the current recommended models. These models all allow commercial use and offer a blend of speed and performance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/models.md`\n- **Observability**（project_doc）：! agent https://raw.githubusercontent.com/neuml/mlflow-txtai/master/images/agent.png 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/observability.md`\n- **Powered by txtai**（project_doc）：The following applications are powered by txtai. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/poweredby.md`\n- **Use Cases**（project_doc）：The following sections introduce common txtai use cases. A comprehensive set of over 70 example notebooks and applications ../examples are also available. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/usecases.md`\n- **Why txtai?**（project_doc）：! why images/why.png only-light ! why images/why-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/why.md`\n- **Configuration**（project_doc）：An agent takes two main arguments, an LLM and a list of tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agent/configuration.md`\n- **Agent**（project_doc）：An agent automatically creates workflows to answer multi-faceted user requests. Agents iteratively prompt and/or interface with tools to step through a process and ultimately come to an answer for a request. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agent/index.md`\n- **Methods**（project_doc）：::: txtai.agent.base.Agent. init ::: txtai.agent.base.Agent. call 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/agent/methods.md`\n- **Distributed embeddings clusters**（project_doc）：The API supports combining multiple API instances into a single logical embeddings index. An example configuration is shown below. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/cluster.md`\n- **Configuration**（project_doc）：Configuration is set through YAML. In most cases, YAML keys map to fields names in Python. The example in the previous section ../ gave a full-featured example covering a wide array of configuration options. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/configuration.md`\n- **Customization**（project_doc）：The txtai API has a number of features out of the box that are designed to help get started quickly. API services can also be augmented with custom code and functionality. The two main ways to do this are with extensions and dependencies. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/customization.md`\n- **API**（project_doc）：! api ../images/api.png only-light ! api ../images/api-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/index.md`\n- **Model Context Protocol**（project_doc）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/mcp.md`\n- **Methods**（project_doc）：::: txtai.api.API options: inherited members: true filters: - \"! del \" - \"!flows\" - \"!function\" - \"!indexes\" - \"!limit\" - \"!pipes\" - \"!read\" - \"!resolve\" - \"!weights\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/methods.md`\n- **OpenAI-compatible API**（project_doc）：The API can be configured to serve an OpenAI-compatible API as shown below. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/openai.md`\n- **Security**（project_doc）：The default implementation of an API service runs via HTTP and is fully open. If the service is being run as a prototype on an internal network, that may be fine. In most scenarios, the connection should at least be encrypted. Authorization is another built-in feature that requires a valid API token with each request. See below for more. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/security.md`\n- **ANN**（project_doc）：Approximate Nearest Neighbor ANN index configuration for storing vector embeddings. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/ann.md`\n- **Cloud**（project_doc）：The following describes parameters used to sync indexes with cloud storage. Cloud object storage, the Hugging Face Hub https://huggingface.co/models and custom providers are all supported. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/cloud.md`\n- **Database**（project_doc）：Databases store metadata, text and binary content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/database.md`\n- **General**（project_doc）：Enables sparse keyword indexing for this embeddings. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/general.md`\n- **Graph**（project_doc）：Enable graph storage via the graph parameter. This component requires the graph ../../../install/ graph extras package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/graph.md`\n- **Configuration**（project_doc）：The following describes available embeddings configuration. These parameters are set in the Embeddings constructor ../methods txtai.embeddings.base.Embeddings. init via either the config parameter or as keyword arguments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/index.md`\n- **Scoring**（project_doc）：Enable scoring support via the scoring parameter. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/scoring.md`\n- **Vectors**（project_doc）：The following covers available vector model configuration options. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/configuration/vectors.md`\n- **Index format**（project_doc）：! format ../images/format.png only-light ! format ../images/format-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/format.md`\n- **Embeddings**（project_doc）：! embeddings ../images/embeddings.png only-light ! embeddings ../images/embeddings-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/index.md`\n- **Index guide**（project_doc）：! indexing ../images/indexing.png only-light ! indexing ../images/indexing-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/indexing.md`\n- **Methods**（project_doc）：::: txtai.embeddings.Embeddings options: filters: - \"!columns\" - \"!createann\" - \"!createcloud\" - \"!createdatabase\" - \"!creategraph\" - \"!createids\" - \"!createindexes\" - \"!createscoring\" - \"!checkarchive\" - \"!configure\" - \"!defaultallowed\" - \"!defaults\" - \"!initindex\" - \"!loadquery\" - \"!loadvectors\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/methods.md`\n- **Query guide**（project_doc）：! query ../images/query.png only-light ! query ../images/query-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/embeddings/query.md`\n- **Audio Mixer**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/audiomixer.md`\n- **Audio Stream**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/audiostream.md`\n- **Microphone**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/microphone.md`\n- **Text To Audio**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/texttoaudio.md`\n- **Text To Speech**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/texttospeech.md`\n- **Transcription**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/audio/transcription.md`\n- **File To HTML**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/filetohtml.md`\n- **HTML To Markdown**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/htmltomd.md`\n- **Segmentation**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/segmentation.md`\n- **Tabular**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/tabular.md`\n- **Textractor**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/textractor.md`\n- **Tokenizer**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/data/tokenizer.md`\n- **Caption**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/image/caption.md`\n- **ImageHash**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/image/imagehash.md`\n- **Objects**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/image/objects.md`\n- **Pipeline**（project_doc）：! pipeline ../images/pipeline.png only-light ! pipeline ../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/index.md`\n- **LLM**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/llm/llm.md`\n- **RAG**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/llm/rag.md`\n- **Entity**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/entity.md`\n- **Labels**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/labels.md`\n- **Reranker**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/reranker.md`\n- **Similarity**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/similarity.md`\n- **Summary**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/summary.md`\n- **Translation**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/text/translation.md`\n- **HFOnnx**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/train/hfonnx.md`\n- **MLOnnx**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/train/mlonnx.md`\n- **HFTrainer**（project_doc）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/pipeline/train/trainer.md`\n- **Workflow**（project_doc）：! workflow ../images/workflow.png only-light ! workflow ../images/workflow-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/index.md`\n- **Schedule**（project_doc）：! schedule ../images/schedule.png only-light ! schedule ../images/schedule-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/schedule.md`\n- **Console Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/console.md`\n- **Export Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/export.md`\n- **File Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/file.md`\n- **Image Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/image.md`\n- **Tasks**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/index.md`\n- **Retrieve Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/retrieve.md`\n- **Service Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/service.md`\n- **Storage Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/storage.md`\n- **Template Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/template.md`\n- **Url Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/url.md`\n- **Workflow Task**（project_doc）：! task ../../images/task.png only-light ! task ../../images/task-dark.png only-dark 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflow/task/workflow.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Installation**（documentation）：! install images/install.png only-light ! install images/install-dark.png only-dark 证据：`docs/install.md`\n- **Why txtai?**（documentation）：txtai is an all-in-one AI framework for semantic search, LLM orchestration and language model workflows. 证据：`README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Cloud**（documentation）：! cloud images/cloud.png only-light ! cloud images/cloud-dark.png only-dark 证据：`docs/cloud.md`\n- **Examples**（documentation）：! examples images/examples.png only-light ! examples images/examples-dark.png only-dark 证据：`docs/examples.md`\n- **FAQ**（documentation）：Below is a list of frequently asked questions and common issues encountered. 证据：`docs/faq.md`\n- **Further reading**（documentation）：! further images/further.png only-light ! further images/further-dark.png only-dark 证据：`docs/further.md`\n- **Index**（documentation）：txtai is an all-in-one AI framework for semantic search, LLM orchestration and language model workflows. 证据：`docs/index.md`\n- **Model guide**（documentation）：See the table below for the current recommended models. These models all allow commercial use and offer a blend of speed and performance. 证据：`docs/models.md`\n- **Observability**（documentation）：! agent https://raw.githubusercontent.com/neuml/mlflow-txtai/master/images/agent.png 证据：`docs/observability.md`\n- **Powered by txtai**（documentation）：The following applications are powered by txtai. 证据：`docs/poweredby.md`\n- **Use Cases**（documentation）：The following sections introduce common txtai use cases. A comprehensive set of over 70 example notebooks and applications ../examples are also available. 证据：`docs/usecases.md`\n- **Why txtai?**（documentation）：! why images/why.png only-light ! why images/why-dark.png only-dark 证据：`docs/why.md`\n- **Configuration**（documentation）：An agent takes two main arguments, an LLM and a list of tools. 证据：`docs/agent/configuration.md`\n- **Agent**（documentation）：An agent automatically creates workflows to answer multi-faceted user requests. Agents iteratively prompt and/or interface with tools to step through a process and ultimately come to an answer for a request. 证据：`docs/agent/index.md`\n- **Methods**（documentation）：::: txtai.agent.base.Agent. init ::: txtai.agent.base.Agent. call 证据：`docs/agent/methods.md`\n- **Distributed embeddings clusters**（documentation）：The API supports combining multiple API instances into a single logical embeddings index. An example configuration is shown below. 证据：`docs/api/cluster.md`\n- **Configuration**（documentation）：Configuration is set through YAML. In most cases, YAML keys map to fields names in Python. The example in the previous section ../ gave a full-featured example covering a wide array of configuration options. 证据：`docs/api/configuration.md`\n- **Customization**（documentation）：The txtai API has a number of features out of the box that are designed to help get started quickly. API services can also be augmented with custom code and functionality. The two main ways to do this are with extensions and dependencies. 证据：`docs/api/customization.md`\n- **API**（documentation）：! api ../images/api.png only-light ! api ../images/api-dark.png only-dark 证据：`docs/api/index.md`\n- **Model Context Protocol**（documentation）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open standard that enables developers to build secure, two-way connections between their data sources and AI-powered tools. 证据：`docs/api/mcp.md`\n- **Methods**（documentation）：::: txtai.api.API options: inherited members: true filters: - \"! del \" - \"!flows\" - \"!function\" - \"!indexes\" - \"!limit\" - \"!pipes\" - \"!read\" - \"!resolve\" - \"!weights\" 证据：`docs/api/methods.md`\n- **OpenAI-compatible API**（documentation）：The API can be configured to serve an OpenAI-compatible API as shown below. 证据：`docs/api/openai.md`\n- **Security**（documentation）：The default implementation of an API service runs via HTTP and is fully open. If the service is being run as a prototype on an internal network, that may be fine. In most scenarios, the connection should at least be encrypted. Authorization is another built-in feature that requires a valid API token with each request. See below for more. 证据：`docs/api/security.md`\n- **ANN**（documentation）：Approximate Nearest Neighbor ANN index configuration for storing vector embeddings. 证据：`docs/embeddings/configuration/ann.md`\n- **Cloud**（documentation）：The following describes parameters used to sync indexes with cloud storage. Cloud object storage, the Hugging Face Hub https://huggingface.co/models and custom providers are all supported. 证据：`docs/embeddings/configuration/cloud.md`\n- **Database**（documentation）：Databases store metadata, text and binary content. 证据：`docs/embeddings/configuration/database.md`\n- **General**（documentation）：Enables sparse keyword indexing for this embeddings. 证据：`docs/embeddings/configuration/general.md`\n- **Graph**（documentation）：Enable graph storage via the graph parameter. This component requires the graph ../../../install/ graph extras package. 证据：`docs/embeddings/configuration/graph.md`\n- **Configuration**（documentation）：The following describes available embeddings configuration. These parameters are set in the Embeddings constructor ../methods txtai.embeddings.base.Embeddings. init via either the config parameter or as keyword arguments. 证据：`docs/embeddings/configuration/index.md`\n- **Scoring**（documentation）：Enable scoring support via the scoring parameter. 证据：`docs/embeddings/configuration/scoring.md`\n- **Vectors**（documentation）：The following covers available vector model configuration options. 证据：`docs/embeddings/configuration/vectors.md`\n- **Index format**（documentation）：! format ../images/format.png only-light ! format ../images/format-dark.png only-dark 证据：`docs/embeddings/format.md`\n- **Embeddings**（documentation）：! embeddings ../images/embeddings.png only-light ! embeddings ../images/embeddings-dark.png only-dark 证据：`docs/embeddings/index.md`\n- **Index guide**（documentation）：! indexing ../images/indexing.png only-light ! indexing ../images/indexing-dark.png only-dark 证据：`docs/embeddings/indexing.md`\n- **Methods**（documentation）：::: txtai.embeddings.Embeddings options: filters: - \"!columns\" - \"!createann\" - \"!createcloud\" - \"!createdatabase\" - \"!creategraph\" - \"!createids\" - \"!createindexes\" - \"!createscoring\" - \"!checkarchive\" - \"!configure\" - \"!defaultallowed\" - \"!defaults\" - \"!initindex\" - \"!loadquery\" - \"!loadvectors\" 证据：`docs/embeddings/methods.md`\n- **Query guide**（documentation）：! query ../images/query.png only-light ! query ../images/query-dark.png only-dark 证据：`docs/embeddings/query.md`\n- **Audio Mixer**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/audiomixer.md`\n- **Audio Stream**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/audiostream.md`\n- **Microphone**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/microphone.md`\n- **Text To Audio**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/texttoaudio.md`\n- **Text To Speech**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/texttospeech.md`\n- **Transcription**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/audio/transcription.md`\n- **File To HTML**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/filetohtml.md`\n- **HTML To Markdown**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/htmltomd.md`\n- **Segmentation**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/segmentation.md`\n- **Tabular**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/tabular.md`\n- **Textractor**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/textractor.md`\n- **Tokenizer**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/data/tokenizer.md`\n- **Caption**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/image/caption.md`\n- **ImageHash**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/image/imagehash.md`\n- **Objects**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/image/objects.md`\n- **Pipeline**（documentation）：! pipeline ../images/pipeline.png only-light ! pipeline ../images/pipeline-dark.png only-dark 证据：`docs/pipeline/index.md`\n- **LLM**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/llm/llm.md`\n- **RAG**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/llm/rag.md`\n- **Entity**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/text/entity.md`\n- **Labels**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/text/labels.md`\n- **Reranker**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/text/reranker.md`\n- **Similarity**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/text/similarity.md`\n- **Summary**（documentation）：! pipeline ../../images/pipeline.png only-light ! pipeline ../../images/pipeline-dark.png only-dark 证据：`docs/pipeline/text/summary.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/install.md`, `README.md`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/install.md`, `README.md`, `LICENSE`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **txtai概述**：importance `high`\n - source_paths: README.md, src/python/txtai/__init__.py\n- **系统架构**：importance `high`\n - source_paths: src/python/txtai/embeddings/base.py, src/python/txtai/workflow/base.py, src/python/txtai/agent/base.py\n- **核心组件**：importance `high`\n - source_paths: src/python/txtai/embeddings/__init__.py, src/python/txtai/pipeline/__init__.py, src/python/txtai/workflow/__init__.py, src/python/txtai/agent/__init__.py\n- **向量嵌入系统**：importance `high`\n - source_paths: src/python/txtai/embeddings/__init__.py, src/python/txtai/embeddings/base.py, src/python/txtai/embeddings/index/__init__.py, src/python/txtai/embeddings/search/__init__.py\n- **近似最近邻索引**：importance `medium`\n - source_paths: src/python/txtai/ann/__init__.py, src/python/txtai/ann/base.py, src/python/txtai/ann/dense/__init__.py, src/python/txtai/ann/dense/factory.py\n- **评分系统**：importance `medium`\n - source_paths: src/python/txtai/scoring/__init__.py, src/python/txtai/scoring/bm25.py, src/python/txtai/scoring/tfidf.py, src/python/txtai/scoring/factory.py\n- **LLM管道**：importance `high`\n - source_paths: src/python/txtai/pipeline/llm/__init__.py, src/python/txtai/pipeline/llm/llm.py, src/python/txtai/pipeline/llm/factory.py, src/python/txtai/pipeline/llm/rag.py\n- **文本处理管道**：importance `high`\n - source_paths: src/python/txtai/pipeline/text/__init__.py, src/python/txtai/pipeline/text/entity.py, src/python/txtai/pipeline/text/labels.py, src/python/txtai/pipeline/text/reranker.py, src/python/txtai/pipeline/text/summary.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `57de5b3a94e888219d543e84fe4b0abdaed94c28`\n- inspected_files: `pyproject.toml`, `README.md`, `docs/further.md`, `docs/why.md`, `docs/index.md`, `docs/usecases.md`, `docs/install.md`, `docs/poweredby.md`, `docs/examples.md`, `docs/cloud.md`, `docs/faq.md`, `docs/models.md`, `docs/observability.md`, `docs/api/customization.md`, `docs/api/security.md`, `docs/api/index.md`, `docs/api/configuration.md`, `docs/api/methods.md`, `docs/api/mcp.md`, `docs/api/openai.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Add `txtai_minimal` package\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add `txtai_minimal` package\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_4e4050b59fdf4d51ac21e82d248e589e | https://github.com/neuml/txtai/issues/1090 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Add custom Captions implementation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Captions implementation\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ff6fe05065564e85a549d7656b85a852 | https://github.com/neuml/txtai/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Add custom Questions pipeline implementation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Questions pipeline implementation\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fa68ea29089d497bb8278c3c360c363c | https://github.com/neuml/txtai/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Add custom Sequences pipeline implementation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Sequences pipeline implementation\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0099afb385ef498d8020521bbf3e9e64 | https://github.com/neuml/txtai/issues/1086 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Add custom Summary pipeline implementation\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Summary pipeline implementation\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9d8f75c31fc6450d8659b310f25d0bf4 | https://github.com/neuml/txtai/issues/1085 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Add minimal Docker build script\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add minimal Docker build script\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_38e1e56a991b412bbc749d2c0b687d54 | https://github.com/neuml/txtai/issues/1092 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Make `transformers` package optional for minimal install\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Make `transformers` package optional for minimal install\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d755829200de4d93b2f4d2f71b36aaf1 | https://github.com/neuml/txtai/issues/1091 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Reduce dependencies to just `numpy` for minimal install\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Reduce dependencies to just `numpy` for minimal install\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_395b735968ab4ec8ad849070d43cd18f | https://github.com/neuml/txtai/issues/1093 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Support minimal install for edge devices\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support minimal install for edge devices\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3ec8e039baf4412888ed3ac543ea1361 | https://github.com/neuml/txtai/issues/1089 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Various training pipeline fixes for v5\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Various training pipeline fixes for v5\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b47325d7496248a993d980c3d59f3269 | https://github.com/neuml/txtai/issues/1088 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：neuml/txtai\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Add `txtai_minimal` package（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Add custom Captions implementation（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Add custom Questions pipeline implementation（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Add custom Sequences pipeline implementation（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Add custom Summary pipeline implementation（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/neuml/txtai 项目说明书\n\n生成时间：2026-05-16 22:15:25 UTC\n\n## 目录\n\n- [txtai概述](#page-overview)\n- [系统架构](#page-architecture)\n- [核心组件](#page-components)\n- [向量嵌入系统](#page-embeddings)\n- [近似最近邻索引](#page-ann-index)\n- [评分系统](#page-scoring)\n- [LLM管道](#page-pipeline-llm)\n- [文本处理管道](#page-pipeline-text)\n- [音频和图像管道](#page-pipeline-audio)\n- [工作流引擎](#page-workflow)\n\n\n\n## txtai概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/neuml/txtai/blob/main/README.md)\n- [setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/embeddings/index/documents.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n- [src/python/txtai/workflow/task/template.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n \n\n# txtai概述\n\n## 1. 项目简介\n\ntxtai是一个全功能AI框架，专为语义搜索、大型语言模型（LLM）编排和语言模型工作流而设计 资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)。\n\n该框架的核心组件是**嵌入数据库（Embeddings Database）**，它将向量索引（稀疏和密集）、图网络和关系数据库结合在一起 资料来源：[README.md:19](https://github.com/neuml/txtai/blob/main/README.md)。\n\n## 2. 核心功能特性\n\ntxtai提供以下主要功能：\n\n| 功能类别 | 描述 |\n|---------|------|\n| 向量搜索 | 支持SQL、对象存储、主题建模、图分析和多模态索引 |\n| 嵌入生成 | 为文本、文档、音频、图像和视频创建嵌入向量 |\n| 管道系统 | 包含LLM提示、问答、标注、转录、翻译等语言模型驱动的管道 |\n| API服务 | 内置FastAPI支持多语言应用开发 |\n| 工作流 | 灵活的工作流引擎支持复杂AI任务编排 |\n| Agent代理 | 构建自主Agent和RAG流程 |\n\n资料来源：[README.md:24-31](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 3. 系统架构\n\n### 3.1 整体架构\n\n```mermaid\ngraph TD\n A[用户应用] --> B[API层 FastAPI]\n B --> C[工作流引擎 Workflow]\n C --> D[管道系统 Pipeline]\n D --> E{任务类型}\n E --> F[数据管道 Data]\n E --> G[LLM管道 LLM]\n E --> H[文本管道 Text]\n E --> I[训练管道 Train]\n F --> J[嵌入数据库 Embeddings]\n G --> J\n J --> K[(向量索引)]\n J --> L[(图网络)]\n J --> M[(关系数据库)]\n```\n\n### 3.2 核心模块关系\n\n```mermaid\ngraph TD\n subgraph 数据处理层\n T[Textractor] --> H2M[HTMLToMarkdown]\n H2M --> SEG[Segmentation]\n end\n \n subgraph 嵌入层\n SEG --> EMB[Embeddings]\n EMB --> DOCS[Documents]\n end\n \n subgraph AI能力层\n EMB --> LLM[LLM Pipeline]\n LLM --> RAG[RAG Pipeline]\n end\n \n subgraph 执行层\n TSK[TemplateTask] --> WFL[Workflow]\n end\n```\n\n## 4. 依赖体系\n\n### 4.1 核心依赖\n\n| 依赖包 | 最低版本 | 用途 |\n|-------|---------|------|\n| faiss-cpu | 1.7.1.post2 | 高效向量相似度搜索 |\n| huggingface-hub | 0.34.0 | Hugging Face模型访问 |\n| torch | 2.4 | 深度学习框架 |\n| transformers | 4.56.2 | 模型推理 |\n| numpy | 1.18.4 | 数值计算 |\n| safetensors | 0.4.5 | 安全模型加载 |\n\n资料来源：[setup.py:28-38](https://github.com/neuml/txtai/blob/main/setup.py)\n\n### 4.2 可选依赖组\n\ntxtai采用模块化设计，通过可选依赖组提供扩展功能：\n\n| 依赖组 | 包含组件 |\n|-------|---------|\n| pipeline-audio | 音频处理管道（onnx, soundfile, webrtcvad等） |\n| pipeline-data | 数据处理管道（beautifulsoup4, docling, nltk等） |\n| pipeline-image | 图像处理管道（pillow, timm, imagehash等） |\n| pipeline-llm | LLM管道（litellm, llama-cpp-python等） |\n| pipeline-text | 文本管道（gliner, sentencepiece等） |\n| pipeline-train | 训练管道（accelerate, peft, onnx等） |\n| agent | Agent代理（jinja2, smolagents, mcpadapt等） |\n| ann | 向量检索（annoy, hnswlib, pgvector等） |\n| api | API服务（fastapi, uvicorn, aiohttp等） |\n| graph | 图数据库（grand-cypher, networkx等） |\n\n资料来源：[setup.py:7-82](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 5. 主要组件详解\n\n### 5.1 嵌入数据库（Embeddings）\n\nEmbeddings是txtai的核心组件，提供向量化的语义搜索能力。\n\n**基本使用示例：**\n\n```python\nimport txtai\n\nembeddings = txtai.Embeddings()\nembeddings.index([\"Correct\", \"Not what we hoped\"])\nresult = embeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md:70-75](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 5.2 文本提取器（Textractor）\n\nTextractor模块负责从各种文件格式中提取文本内容。\n\n```python\nclass Textractor(Segmentation):\n def __init__(\n self,\n sentences=False, # 按句子分割\n lines=False, # 按行分割\n paragraphs=False, # 按段落分割\n minlength=None, # 最小文本长度\n join=False, # 是否合并结果\n sections=False, # 保留章节结构\n cleantext=True, # 清理文本\n chunker=None, # 分块器\n headers=None, # HTTP请求头\n backend=\"available\", # 后端选择\n safeopen=False, # 安全打开模式\n ):\n```\n\n**支持的输入格式：**\n\nTextractor内部使用FileToHTML管道处理文件，并支持Tika后端作为备选方案。\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:15-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n\n### 5.3 LLM管道\n\nLLM管道提供大型语言模型的调用能力，支持多种模型后端。\n\n**核心方法：**\n\n| 方法 | 描述 |\n|------|------|\n| `__call__(text, ...)` | 生成文本内容 |\n| `ischat()` | 检查是否为聊天模型 |\n| `isvision()` | 检查是否支持视觉功能 |\n\n**调用参数：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| text | str/list | - | 输入文本 |\n| maxlength | int | None | 最大序列长度 |\n| stream | bool | False | 是否流式输出 |\n| stop | list | None | 停止字符串列表 |\n| defaultrole | str | \"auto\" | 默认角色 |\n| stripthink | bool | None | 是否去除思考标签 |\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:20-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n\n### 5.4 工作流引擎（Workflow）\n\n工作流引擎支持灵活的任务编排。\n\n**TemplateTask组件：**\n\nTemplateTask使用模板生成LLM提示词，支持字典和元组两种参数传递方式：\n\n```python\n# 字典参数传递\nself.formatter.format(self.template, **element)\n\n# 元组参数传递\nself.formatter.format(self.template, **{f\"arg{i}\": x for i, x in enumerate(element)})\n\n# 默认行为 - 使用{text}参数\nself.formatter.format(self.template, text=element)\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:35-50](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n\n## 6. RAG快速入门\n\n### 6.1 完整流程\n\n```mermaid\ngraph LR\n A[加载文档] --> B[文本提取 Textractor]\n B --> C[文本分块]\n C --> D[构建嵌入索引]\n D --> E[创建RAG管道]\n E --> F[用户提问]\n F --> G[语义检索]\n G --> H[上下文组装]\n H --> I[LLM生成答案]\n```\n\n### 6.2 代码示例\n\n```python\nfrom txtai import Embeddings\nfrom txtai.pipeline import RAG, Textractor\n\n# Step 1: 文本提取\ntextractor = Textractor()\nf = \"document.pdf\"\nchunks = []\nfor chunk in textractor(f):\n chunks.append((f, chunk))\n\n# Step 2: 构建嵌入数据库\nembeddings = Embeddings(\n content=True, \n path=\"Qwen/Qwen3-Embedding-0.6B\", \n maxlength=2048\n)\nembeddings.index(chunks)\n\n# Step 3: 创建RAG管道\ntemplate = \"\"\"\n Answer the following question using the provided context.\n\n Question: {question}\n Context: {context}\n\"\"\"\n\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# Step 4: 问答\nquestion = \"Summarize the main advancements made by BERT\"\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py:1-50](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## 7. 文档存储机制\n\n### 7.1 Documents类\n\nDocuments类负责管理索引文档的存储和序列化：\n\n```python\nclass Documents:\n def add(self, documents):\n \"\"\"添加文档批次\"\"\"\n if not self.documents:\n self.documents = tempfile.NamedTemporaryFile(\n mode=\"wb\", suffix=\".docs\", delete=False\n )\n \n # 流式保存文档\n self.serializer.savestream(documents, self.documents)\n self.batch += 1\n self.size += len(documents)\n return documents\n \n def close(self):\n \"\"\"关闭并清理临时文件\"\"\"\n os.remove(self.documents.name)\n self.documents = None\n self.batch = 0\n self.size = 0\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:10-30](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n## 8. 部署方式\n\n### 8.1 API服务部署\n\n通过YAML配置文件快速启动API服务：\n\n```yaml\n# app.yml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n```\n\n```bash\nCONFIG=app.yml uvicorn \"txtai.api:app\"\ncurl -X GET \"http://localhost:8000/search?query=positive\"\n```\n\n### 8.2 工作流API\n\n```python\ndef api(self, config):\n \"\"\"启动内部uvicorn服务器\"\"\"\n # 生成临时工作流配置文件\n workflow = os.path.join(tempfile.gettempdir(), \"workflow.yml\")\n with open(workflow, \"w\", encoding=\"utf-8\") as f:\n f.write(config)\n \n os.environ[\"CONFIG\"] = workflow\n txtai.api.application.start()\n```\n\n资料来源：[examples/workflows.py:60-75](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n\n## 9. 技术特点\n\n| 特点 | 说明 |\n|------|------|\n| 低占用 | 仅安装必要依赖，可按需扩展 |\n| 本地运行 | 无需将数据发送到外部服务 |\n| 模型兼容 | 支持从小型模型到LLM的多种规模 |\n| 灵活扩展 | 模块化设计，易于集成新功能 |\n| 多模态 | 支持文本、文档、音频、图像和视频 |\n\n资料来源：[README.md:80-85](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 10. 安装方式\n\n### 10.1 基础安装\n\n```bash\npip install txtai\n```\n\n### 10.2 可选组件安装\n\n```bash\n# 仅向量搜索\npip install txtai[ann]\n\n# 包含向量搜索\npip install txtai[vectors]\n\n# 完整安装\npip install txtai[all]\n\n# 特定功能\npip install txtai[api] # API服务\npip install txtai[agent] # Agent代理\npip install txtai[pipeline-llm] # LLM支持\npip install txtai[graph] # 图数据库\n```\n\n资料来源：[setup.py:85-110](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 11. 总结\n\ntxtai是一个功能全面的AI框架，通过将向量搜索、图数据库和关系数据库相结合，为构建语义搜索、RAG系统和AI工作流提供了统一的基础设施。其模块化设计和丰富的可选依赖使其能够适应从简单到复杂的各种应用场景。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[核心组件](#page-components), [向量嵌入系统](#page-embeddings), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n- [src/python/txtai/workflow/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/base.py)\n- [src/python/txtai/agent/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/base.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/embeddings/index/documents.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n- [examples/workflows.py](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n \n\n# 系统架构\n\n## 概述\n\ntxtai 是一个功能全面的 AI 框架，核心定位为**语义搜索**、**LLM 编排**和**语言模型工作流**的一体化解决方案。该框架的关键组件是**嵌入数据库（Embeddings Database）**，它整合了向量索引（稀疏和密集）、图网络和关系数据库的能力。\n\n这种架构设计使得 txtai 不仅能够执行向量搜索，还能作为大型语言模型（LLM）应用的强大知识源，支持构建自主代理（Agents）、检索增强生成（RAG）流程、多模态工作流等高级应用场景。\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 整体架构\n\ntxtai 采用模块化设计，核心架构由以下几个主要层次组成：\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n API[API 服务层]\n Console[Console 控制台]\n end\n \n subgraph \"应用层\"\n Agent[Agent 代理]\n Workflow[Workflow 工作流]\n RAG[RAG 管道]\n end\n \n subgraph \"管道层\"\n LLM[LLM 管道]\n Data[Data 数据管道]\n Text[Text 文本管道]\n Audio[Audio 音频管道]\n Image[Image 图像管道]\n end\n \n subgraph \"核心层\"\n Embeddings[Embeddings 嵌入数据库]\n Graph[Graph 图网络]\n Database[Database 数据库]\n end\n \n subgraph \"向量索引层\"\n FAISS[FAISS]\n HNSW[HNSWLib]\n Annoy[Annoy]\n PGVector[PGVector]\n end\n \n API --> Agent\n API --> Workflow\n Agent --> Workflow\n Workflow --> Embeddings\n Workflow --> LLM\n RAG --> Embeddings\n RAG --> LLM\n Embeddings --> FAISS\n Embeddings --> HNSW\n Embeddings --> Annoy\n Embeddings --> PGVector\n Embeddings --> Graph\n Embeddings --> Database\n```\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 核心模块\n\n### 1. 嵌入数据库（Embeddings）\n\n嵌入数据库是 txtai 的核心组件，它统一了向量索引、图网络和关系数据库的功能。\n\n#### 核心类结构\n\n```python\nclass Embeddings:\n def __init__(self, content=True, path=\"model\", maxlength=2048):\n self.content = content\n self.path = path\n self.maxlength = maxlength\n \n def index(self, documents): ...\n def search(self, query, limit=10): ...\n def batch(self, documents): ...\n```\n\n#### 功能特性\n\n| 特性 | 描述 | 支持类型 |\n|------|------|----------|\n| 向量搜索 | 稀疏和密集向量索引 | FAISS, HNSW, Annoy, PGVector |\n| 内容存储 | 文档内容持久化 | msgpack 序列化 |\n| SQL 查询 | 混合搜索能力 | SQLAlchemy |\n| 图分析 | 图网络遍历 | NetworkX, Grand |\n| 多模态 | 支持多种数据类型 | 文本、图像、音视频 |\n\n资料来源：[src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n\n#### 文档存储机制\n\n嵌入数据库使用临时文件系统存储文档数据，支持批量索引操作：\n\n```python\n# documents.py 中的关键实现\nif not self.documents:\n self.documents = tempfile.NamedTemporaryFile(mode=\"wb\", suffix=\".docs\", delete=False)\n\n# 批量添加文档\nself.serializer.savestream(documents, self.documents)\nself.batch += 1\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:2-15](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n### 2. 工作流引擎（Workflow）\n\n工作流引擎负责编排和组织多个任务（Task）的执行流程。\n\n#### 工作流结构\n\n```mermaid\ngraph LR\n subgraph \"工作流定义\"\n Config[YAML 配置]\n Tasks[任务列表]\n end\n \n subgraph \"任务类型\"\n Action[Action 动作]\n Service[Service 服务]\n Transform[Transform 转换]\n end\n \n Config --> Tasks\n Tasks --> Action\n Tasks --> Service\n Tasks --> Transform\n```\n\n#### 支持的任务类型\n\n| 任务类型 | 说明 | 配置方式 |\n|----------|------|----------|\n| `action` | 执行动作任务 | `{\"action\": \"taskname\"}` |\n| `service` | 启动服务任务 | `{\"task\": \"service\"}` |\n| `textractor` | 文本提取任务 | `{\"action\": \"textractor\", \"task\": \"url\"}` |\n| `transcription` | 音频转录任务 | `{\"action\": \"transcription\", \"task\": \"url\"}` |\n| `tabular` | 表格处理任务 | `{\"action\": \"tabular\"}` |\n| `summary` | 摘要生成任务 | `{\"action\": \"summary\", \"path\": \"model\"}` |\n\n资料来源：[examples/workflows.py](https://github.com/neuml/txtai/blob/main/examples/workflows.py)\n\n#### 模板任务（Template Task）\n\n模板任务用于生成 LLM 提示词，支持多种输入格式：\n\n```python\nclass TemplateTask(Task):\n def prepare(self, element):\n # 字典输入 - 作为命名参数传递\n if isinstance(element, dict):\n return self.formatter.format(self.template, **element)\n \n # 元组输入 - 作为 arg0-argN 传递\n if isinstance(element, tuple):\n return self.formatter.format(self.template, **{f\"arg{i}\": x for i, x in enumerate(element)})\n \n # 默认 - 使用 {text} 参数\n return self.formatter.format(self.template, text=element)\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:30-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/template.py)\n\n### 3. 代理系统（Agent）\n\n代理系统支持构建自主 AI 代理，具备规划、推理和执行能力。\n\n```mermaid\ngraph TD\n Agent[Agent 代理] --> Tool1[工具 1]\n Agent --> Tool2[工具 2]\n Agent --> ToolN[工具 N]\n Agent --> LLM[LLM 引擎]\n \n Tool1 --> Memory[记忆存储]\n Tool2 --> Memory\n ToolN --> Memory\n \n LLM --> Action[执行动作]\n Action --> Tool1\n Action --> Tool2\n Action --> ToolN\n```\n\n#### 代理特性\n\n- 支持多种 LLM 后端（Hugging Face、Ollama、vLLM、llama.cpp）\n- 集成 MCP（Model Context Protocol）适配器\n- 支持 Jinja2 模板渲染\n- 可与工作流系统无缝集成\n\n资料来源：[src/python/txtai/agent/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/base.py)\n\n### 4. 管道系统（Pipeline）\n\n管道系统是数据处理的核心，提供多种专门的处理器。\n\n#### 管道类型\n\n| 管道类型 | 功能 | 依赖库 |\n|----------|------|--------|\n| LLM 管道 | 语言模型推理、提示执行 | transformers, llama-cpp |\n| Data 管道 | 文本提取、HTML 转换、分段 | beautifulsoup4, tika, nltk |\n| Audio 管道 | 语音转文本、翻译 | scipy, soundfile |\n| Image 管道 | 图像处理、特征提取 | pillow, timm |\n| Text 管道 | 文本分类、实体识别 | gliner, staticvectors |\n\n#### 文本提取器（Textractor）\n\n文本提取器是数据管道的重要组成部分，支持从多种格式提取文本：\n\n```python\nclass Textractor(Segmentation):\n def __init__(\n self,\n sentences=False, # 句子分割\n lines=False, # 行分割\n paragraphs=False, # 段落分割\n minlength=None, # 最小文本长度\n join=False, # 合并短文本\n sections=False, # 保留章节结构\n cleantext=True, # 清理文本\n chunker=None, # 分块器\n backend=\"available\", # 后端: tika 或自动\n safeopen=False, # 安全打开模式\n ):\n```\n\n处理流程：\n\n```mermaid\ngraph LR\n Input[输入文件/URL] --> FileToHTML[FileToHTML]\n FileToHTML --> HTMLToMarkdown[HTMLToMarkdown]\n HTMLToMarkdown --> Segmentation[Segmentation]\n Segmentation --> Output[文本输出]\n```\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:14-40](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n\n#### LLM 管道\n\nLLM 管道负责与语言模型交互：\n\n```python\nclass LLM:\n def __call__(\n self,\n text, # 输入文本或列表\n maxlength=None, # 最大序列长度\n stream=False, # 流式响应\n stop=None, # 停止字符串列表\n defaultrole=\"auto\", # 默认角色\n stripthink=True, # 移除思考标签\n **kwargs # 其他生成参数\n ):\n return self.generator(text, maxlength, stream, stop, defaultrole, stripthink, **kwargs)\n \n def ischat(self): ... # 检查是否为聊天模型\n def isvision(self): ... # 检查是否支持视觉\n```\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:20-45](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n\n## 应用场景架构\n\n### 检索增强生成（RAG）\n\n```mermaid\ngraph TD\n Question[用户问题] --> Embeddings[Embeddings 查询]\n Embeddings --> Context[上下文检索]\n Context --> LLM[LLM 生成]\n LLM --> Answer[生成回答]\n \n subgraph \"索引流程\"\n Documents[文档] --> Textractor[文本提取]\n Textractor --> Chunks[文本块]\n Chunks --> Index[向量索引]\n end\n```\n\nRAG 应用示例：\n\n```python\n# 创建嵌入数据库\nembeddings = Embeddings(content=True, path=\"Qwen/Qwen3-Embedding-0.6B\", maxlength=2048)\nembeddings.index(chunks)\n\n# 创建 RAG 管道\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# 执行查询\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n### API 服务架构\n\n```mermaid\ngraph LR\n Request[HTTP 请求] --> FastAPI[FastAPI 服务]\n FastAPI --> Workflow[Workflow 引擎]\n Workflow --> Pipeline[Pipeline 管道]\n Pipeline --> Embeddings[Embeddings]\n Pipeline --> LLM[LLM]\n Workflow --> Response[JSON 响应]\n```\n\nAPI 配置示例（YAML）：\n\n```yaml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n\nworkflow:\n search:\n tasks:\n - action: similarity\n```\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 依赖关系\n\ntxtai 的依赖组织结构如下：\n\n```mermaid\ngraph TD\n Core[核心依赖] --> Torch[torch>=2.4]\n Core --> Transformers[transformers>=4.56.2]\n Core --> Faiss[faiss-cpu>=1.7.1]\n Core --> HuggingFace[huggingface-hub>=0.34.0]\n \n Optional[可选依赖] --> API[API: fastapi, uvicorn]\n Optional --> ANN[ANN: hnswlib, annoy, pgvector]\n Optional --> LLM[LLM: litellm, llama-cpp]\n Optional --> Cloud[Cloud: apache-libcloud]\n```\n\n## 扩展组件\n\n| 组件类别 | 包名 | 主要功能 |\n|----------|------|----------|\n| 图数据库 | `graph` | Grand-Cypher 图查询 |\n| 关系数据库 | `database` | DuckDB, SQLAlchemy |\n| 向量索引 | `ann` | 多种 ANN 算法支持 |\n| 云存储 | `cloud` | Apache Libcloud 集成 |\n| 模型优化 | `model` | ONNX 推理优化 |\n\n## 配置选项\n\n### Embeddings 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `path` | str | - | 模型路径（Hugging Face 模型名或本地路径） |\n| `content` | bool | False | 是否存储原始内容 |\n| `maxlength` | int | 256 | 最大序列长度 |\n| `functions` | dict | None | 函数调用配置 |\n| `scoring` | str | None | 评分方法 |\n| `indextype` | str | None | 索引类型（hnsw, annoy, faiss 等） |\n\n### Workflow 任务配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `action` | str | 任务动作名称 |\n| `task` | str | 任务类型 |\n| `args` | list | 位置参数 |\n| `config` | dict | 任务特定配置 |\n\n## 总结\n\ntxtai 采用分层模块化架构设计，核心优势包括：\n\n1. **统一性**：通过 Embeddings 数据库统一向量搜索、图分析和关系查询\n2. **可扩展性**：丰富的可选依赖支持按需扩展功能\n3. **灵活性**：Pipeline 管道支持自定义数据处理流程\n4. **生产级**：内置 API 服务支持快速部署\n\n该架构设计使得 txtai 能够从小型嵌入模型无缝扩展到完整的 LLM 应用，满足从原型开发到生产部署的全流程需求。\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [向量嵌入系统](#page-embeddings), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/__init__.py)\n- [src/python/txtai/pipeline/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/__init__.py)\n- [src/python/txtai/workflow/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/__init__.py)\n- [src/python/txtai/agent/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/__init__.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/agent/tool/function.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/tool/function.py)\n- [src/python/txtai/agent/tool/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/agent/tool/factory.py)\n \n\n# 核心组件\n\ntxtai 是一个功能全面的 AI 框架，其核心架构由四个主要组件构成：嵌入向量数据库（Embeddings）、管道（Pipeline）、工作流（Workflow）和智能体（Agent）。这些组件协同工作，为语义搜索、大型语言模型（LLM）应用和知识图谱分析提供统一的基础设施。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[txtai 核心架构] --> B[Embeddings 嵌入向量数据库]\n A --> C[Pipeline 管道]\n A --> D[Workflow 工作流]\n A --> E[Agent 智能体]\n \n B --> B1[向量索引]\n B --> B2[图网络]\n B --> B3[关系数据库]\n \n C --> C1[LLM 管道]\n C --> C2[Summary 摘要]\n C --> C3[Textractor 文本提取]\n C --> C4[RAG 检索增强生成]\n \n D --> D1[Task 任务]\n D --> D2[Template 模板]\n \n E --> E1[Tool 工具]\n E --> E2[FunctionTool 函数工具]\n```\n\n## 1. 嵌入向量数据库（Embeddings）\n\n### 概述\n\n嵌入向量数据库是 txtai 的核心组件，它将向量索引（稀疏和密集）、图网络和关系数据库有机结合。这种独特的架构设计使得 txtai 能够同时支持向量搜索和传统数据库查询，为大型语言模型应用提供强大的知识源支持。\n\n### 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 向量搜索 | 支持语义相似度检索 |\n| 混合索引 | 稀疏与密集向量结合 |\n| SQL 支持 | 关系型数据查询 |\n| 图分析 | 知识图谱网络分析 |\n| 内容存储 | 文档和元数据存储 |\n\n### 使用方式\n\n```python\nimport txtai\n\nembeddings = txtai.Embeddings()\nembeddings.index([\"Correct\", \"Not what we hoped\"])\nresult = embeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md]()\n\n## 2. 管道（Pipeline）\n\n### 概述\n\n管道是 txtai 中用于处理数据的核心模块，由语言模型驱动。管道可以执行 LLM 提示、问答、标注、转录、翻译等任务。\n\n### LLM 管道\n\nLLM 管道是 txtai 中最重要的管道之一，支持多种模型类型和调用方式。\n\n#### 支持的模型类型\n\n- Hugging Face Transformers 模型\n- llama.cpp 本地模型\n- Ollama 远程模型\n- vLLM 服务\n\n#### API 参数\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| text | str/list | 必需 | 输入文本或文本列表 |\n| maxlength | int | 512 | 最大序列长度 |\n| stream | bool | False | 是否流式输出 |\n| stop | list | None | 停止字符串列表 |\n| defaultrole | str | \"auto\" | 默认角色（user/prompt） |\n| stripthink | bool | 自动 | 是否移除思考标签 |\n\n```python\nfrom txtai.pipeline import Summary, Textractor\n\n# 文本摘要管道\nsummary = Summary(\"sshleifer/distilbart-cnn-12-6\")\n\n# 文本提取管道\ntextract = Textractor(paragraphs=True, minlength=100, join=True)\n```\n\n资料来源：[src/python/txtai/pipeline/llm/llm.py:1-80]()\n\n### 数据管道\n\nTextractor 模块负责从各种文件格式中提取文本内容。\n\n#### Textractor 参数\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| sentences | bool | False | 按句子分割 |\n| lines | bool | False | 按行分割 |\n| paragraphs | bool | False | 按段落分割 |\n| minlength | int | None | 最小文本长度 |\n| join | bool | False | 合并结果 |\n| sections | bool | False | 按章节处理 |\n| cleantext | bool | True | 清理文本 |\n| chunker | str | None | 分块器 |\n| backend | str | \"available\" | 后端（tika/none） |\n| safeopen | bool/str | False | 安全打开模式 |\n\n```python\ntextractor = Textractor(\n paragraphs=True,\n minlength=100,\n join=True,\n backend=\"available\"\n)\n```\n\n资料来源：[src/python/txtai/pipeline/data/textractor.py:1-60]()\n\n## 3. 工作流（Workflow）\n\n### 概述\n\n工作流系统允许将多个任务串联起来处理数据。通过定义任务序列，可以构建复杂的数据处理管道。\n\n```mermaid\ngraph LR\n A[输入数据] --> B[Task 1]\n B --> C[Task 2]\n C --> D[Task N]\n D --> E[输出结果]\n```\n\n### 任务类型\n\n| 任务类型 | 描述 |\n|----------|------|\n| Task | 基础任务 |\n| TemplateTask | 模板任务，用于生成 LLM 提示 |\n| UrlTask | URL 处理任务 |\n\n### 模板任务\n\nTemplateTask 是工作流中的重要组件，用于根据模板和任务输入生成文本。模板可以用于准备 LLM 提示数据。\n\n```python\nfrom txtai.workflow import UrlTask, Task, Workflow\n\n# 定义工作流\nworkflow = Workflow([UrlTask(textract), Task(summary)])\n\n# 执行工作流\nresult = list(workflow([url]))[0]\n```\n\n资料来源：[src/python/txtai/workflow/task/template.py:1-50]()\n\n## 4. 智能体（Agent）\n\n### 概述\n\n智能体系统用于构建自主代理，支持构建检索增强生成（RAG）流程、多模态工作流等高级应用。\n\n```mermaid\ngraph TD\n A[Agent 智能体] --> B[Tool 工具集]\n A --> C[LLM 大语言模型]\n B --> D[FunctionTool 函数工具]\n B --> E[EmbeddingsTool 嵌入工具]\n C --> F[推理引擎]\n \n F --> G[规划决策]\n G --> H[工具调用]\n H --> I[结果反馈]\n I --> F\n```\n\n### 工具系统\n\ntxtai 的工具系统支持三种创建方式：\n\n| 创建方式 | 描述 |\n|----------|------|\n| Tool 实例 | 直接传入 Tool 对象 |\n| 字典配置 | 包含 name、description、inputs、target 的配置字典 |\n| 字符串别名 | 使用预定义的工具名称 |\n\n#### FunctionTool 类\n\nFunctionTool 将描述性配置与目标函数结合，注入到 LLM 提示中。\n\n```python\nfrom txtai.agent.tool.function import FunctionTool\n\nconfig = {\n \"name\": \"my_function\",\n \"description\": \"执行特定操作\",\n \"inputs\": {\"param1\": \"string\"},\n \"output\": \"string\",\n \"target\": my_function\n}\n\ntool = FunctionTool(config)\n```\n\n资料来源：[src/python/txtai/agent/tool/function.py:1-60]()\n\n### 工具工厂\n\nToolFactory 负责根据配置创建工具实例，支持以下功能：\n\n- 从函数和文档创建工具\n- 从输入字典创建工具\n- 从字符串别名获取默认工具\n- 导入 MCP 工具集合\n\n```python\nfrom txtai.agent.tool.factory import ToolFactory\n\n# 创建工具列表\ntools = ToolFactory.create(config)\n```\n\n资料来源：[src/python/txtai/agent/tool/factory.py:1-80]()\n\n## 5. RAG 检索增强生成\n\n### 概述\n\nRAG 是 txtai 中的重要应用模式，它将嵌入向量数据库与 LLM 结合，实现基于知识库的问答系统。\n\n```mermaid\ngraph TD\n A[用户问题] --> B[Embeddings 查询]\n B --> C[检索相关上下文]\n C --> D[构建提示模板]\n D --> E[LLM 生成答案]\n E --> F[返回结果]\n```\n\n### 使用示例\n\n```python\nfrom txtai import Embeddings, RAG\n\n# 用户提示模板\ntemplate = \"\"\"\n Answer the following question using the provided context.\n\n Question:\n {question}\n\n Context:\n {context}\n\"\"\"\n\nrag = RAG(\n embeddings,\n \"Qwen/Qwen3-0.6B\",\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\nquestion = \"Summarize the main advancements made by BERT\"\nresult = rag(question, maxlength=2048, stripthink=True)\n```\n\n资料来源：[examples/rag_quickstart.py]()\n\n## 组件依赖关系\n\n```mermaid\ngraph TD\n subgraph 核心层\n A[txtai] --> B[Embeddings]\n A --> C[Pipeline]\n A --> D[Workflow]\n A --> E[Agent]\n end\n \n subgraph 管道层\n C --> C1[LLM Pipeline]\n C --> C2[Summary Pipeline]\n C --> C3[Textractor Pipeline]\n C --> C4[RAG Pipeline]\n end\n \n subgraph 应用层\n E --> F[RAG 应用]\n E --> G[自主代理]\n D --> H[数据处理]\n end\n \n B --> I[向量索引]\n B --> J[关系数据库]\n```\n\n## 总结\n\ntxtai 的四大核心组件构成了一个完整的 AI 应用开发框架：\n\n1. **Embeddings** 提供向量搜索和知识存储能力\n2. **Pipeline** 提供数据处理和模型推理能力\n3. **Workflow** 提供任务编排和工作流自动化\n4. **Agent** 提供智能体和自主决策能力\n\n这些组件可以独立使用，也可以组合使用来构建复杂的 AI 应用，如 RAG 系统、多模态工作流和自主代理。\n\n---\n\n\n\n## 向量嵌入系统\n\n### 相关页面\n\n相关主题：[近似最近邻索引](#page-ann-index), [评分系统](#page-scoring), [核心组件](#page-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/embeddings/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/__init__.py)\n- [src/python/txtai/embeddings/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/base.py)\n- [src/python/txtai/embeddings/index/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/__init__.py)\n- [src/python/txtai/embeddings/search/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/search/__init__.py)\n- [README.md](https://github.com/neuml/txtai/blob/main/README.md)\n- [setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n- [examples/rag_quickstart.py](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n \n\n# 向量嵌入系统\n\n## 概述\n\ntxtai 的核心组件是**向量嵌入系统（Embeddings System）**，它是一个将向量索引、图网络和关系数据库统一结合的嵌入数据库。该系统为语义搜索和大语言模型（LLM）应用提供了强大的知识检索基础。\n\n向量嵌入系统的主要特点包括：\n\n- 支持文本、文档、音视频等多模态内容的嵌入表示\n- 集成稀疏和密集向量索引\n- 支持向量搜索与 SQL 查询的混合检索\n- 提供本地化运行能力，无需依赖外部远程服务\n- 支持从小型模型到大型语言模型（LLM）的多种配置\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n## 系统架构\n\n向量嵌入系统的架构设计采用分层模块化结构，核心由索引模块、搜索模块和基础抽象层组成。\n\n```mermaid\ngraph TD\n A[\"txtai.Embeddings
入口类\"] --> B[\"EmbeddingsBase
基础抽象类\"]\n B --> C[\"EmbeddingsIndex
索引管理\"]\n B --> D[\"EmbeddingsSearch
搜索管理\"]\n C --> E[\"Documents
文档序列化\"]\n C --> F[\"Vectors
向量存储\"]\n D --> G[\"VectorQueue
向量队列\"]\n D --> H[\"HNSW/FAISS等
索引后端\"]\n```\n\n### 核心模块职责\n\n| 模块 | 职责 | 主要功能 |\n|------|------|----------|\n| `Embeddings` | 入口类 | 提供 `index()`、`search()` 等核心 API |\n| `EmbeddingsBase` | 基础抽象 | 定义通用接口和默认实现 |\n| `EmbeddingsIndex` | 索引管理 | 管理文档和向量的索引构建流程 |\n| `EmbeddingsSearch` | 搜索管理 | 处理向量相似度搜索请求 |\n| `Documents` | 文档序列化 | 将输入数据序列化为流式存储格式 |\n\n## Embeddings 入口类\n\n`txtai.Embeddings` 是用户使用向量嵌入系统的主要入口点，提供了简洁的 API 接口。\n\n### 基础使用示例\n\n```python\nimport txtai\n\n# 创建嵌入实例\nembeddings = txtai.Embeddings()\n\n# 索引文档\nembeddings.index([\"正确\", \"不是我们希望的\"])\n\n# 执行语义搜索\nembeddings.search(\"positive\", 1)\n# 返回: [(0, 0.29862046241760254)]\n```\n\n资料来源：[README.md:1-12](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 构造函数参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `path` | str | None | 向量模型路径，支持 Hugging Face 模型、llama.cpp、Ollama、vLLM |\n| `content` | bool | False | 是否存储原始文档内容 |\n| `vectors` | str | None | 外部向量文件路径 |\n| `functions` | list | None | 自定义向量生成函数列表 |\n| `scoring` | bool | True | 是否启用相似度评分 |\n| `gpu` | bool | True | 是否优先使用 GPU |\n| `batchsize` | int | 32 | 批处理大小 |\n| `maxlength` | int | 512 | 最大序列长度 |\n| `quantize` | bool | False | 是否量化模型 |\n\n资料来源：[examples/rag_quickstart.py:18-19](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## 索引构建流程\n\n### 索引 API\n\n```python\n# 使用 content=True 存储原始文档\nembeddings = Embeddings(content=True, path=\"Qwen/Qwen3-Embedding-0.6B\", maxlength=2048)\nembeddings.index(chunks)\n```\n\n索引过程接受元组列表 `(id, data, vector)` 或 `(id, data)` 格式的数据，自动生成向量表示。\n\n资料来源：[examples/rag_quickstart.py:18-20](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n### 文档序列化\n\n索引模块使用流式序列化机制处理文档数据：\n\n```python\n# Documents 类负责序列化\nself.documents = tempfile.NamedTemporaryFile(mode=\"wb\", suffix=\".docs\", delete=False)\nself.serializer.savestream(documents, self.documents)\n```\n\n序列化设计支持增量索引，可以分批次添加文档：\n\n```python\n# 分批添加文档\nself.batch += 1\nself.size += len(documents)\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:2-10](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n### 索引关闭与清理\n\n索引完成后，系统会清理临时资源：\n\n```python\ndef close(self):\n # 清理流文件\n os.remove(self.documents.name)\n # 重置文档参数\n self.documents = None\n self.batch = 0\n self.size = 0\n```\n\n资料来源：[src/python/txtai/embeddings/index/documents.py:22-30](https://github.com/neuml/txtai/blob/main/src/python/txtai/embeddings/index/documents.py)\n\n## 搜索流程\n\n### 语义搜索 API\n\n```python\n# 执行向量相似度搜索\nresults = embeddings.search(\"查询文本\", topk=5)\n```\n\n搜索返回格式为 `[(document_id, score), ...]`，按相似度降序排列。\n\n### 向量队列机制\n\n搜索模块使用 `VectorQueue` 管理搜索请求队列，支持并发搜索操作。\n\n```mermaid\ngraph LR\n A[\"search(query)\"] --> B[\"VectorQueue
请求队列\"]\n B --> C[\"HNSW/FAISS
向量索引\"]\n C --> D[\"排序过滤\"]\n D --> E[\"返回结果\"]\n```\n\n### 支持的向量索引后端\n\n| 后端 | 安装包 | 说明 |\n|------|--------|------|\n| FAISS | `faiss-cpu>=1.7.1.post2` | 默认后端，高性能稠密向量检索 |\n| HNSW | `hnswlib>=0.5.0` | 层次可导航小世界图 |\n| Annoy | `annoy>=1.16.3` | Spotify 的近似最近邻库 |\n| pgvector | `pgvector>=0.4.1` | PostgreSQL 向量扩展 |\n\n资料来源：[setup.py:15-40](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 配置与扩展\n\n### 模型路径配置\n\ntxtai 支持多种模型格式和来源：\n\n```yaml\n# app.yml\nembeddings:\n path: sentence-transformers/all-MiniLM-L6-v2\n```\n\n```python\n# 支持的配置方式\nembeddings = Embeddings(path=\"sentence-transformers/all-MiniLM-L6-v2\")\nembeddings = Embeddings(path=\"Qwen/Qwen3-Embedding-0.6B\") # Hugging Face 模型\nembeddings = Embeddings(path=\"llama.cpp/model.bin\") # 本地 llama.cpp 模型\n```\n\n### 依赖安装\n\n核心依赖（默认安装）：\n\n```python\ndefault = [\n \"faiss-cpu>=1.7.1.post2\",\n \"huggingface-hub>=0.34.0\",\n \"msgpack>=1.0.7\",\n \"numpy>=1.18.4\",\n \"regex>=2022.8.17\",\n \"pyyaml>=5.3\",\n \"safetensors>=0.4.5\",\n \"torch>=2.4\",\n \"transformers>=4.56.2\",\n]\n```\n\n向量索引扩展依赖：\n\n```python\nextras[\"ann\"] = [\n \"annoy>=1.16.3\",\n \"hnswlib>=0.5.0\",\n \"pgvector>=0.4.1\",\n \"scikit-learn>=0.23.1\",\n \"scipy>=1.4.1\",\n]\n\nextras[\"vectors\"] = [\n \"model2vec>=0.3.0\",\n \"sentence-transformers>=5.0.0\",\n \"staticvectors>=0.2.0\",\n]\n```\n\n资料来源：[setup.py:15-30](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 与 RAG 系统集成\n\n向量嵌入系统是检索增强生成（RAG）的基础组件，负责从知识库中检索相关上下文。\n\n```python\n# 创建 RAG 管道\nrag = RAG(\n embeddings, # 嵌入数据库\n \"Qwen/Qwen3-0.6B\", # LLM 模型\n system=\"You are a friendly assistant\",\n template=template,\n output=\"flatten\",\n)\n\n# 执行问答\nresult = rag(\"Summarize BERT advancements\", maxlength=2048, stripthink=True)\n```\n\n工作流程：\n\n```mermaid\ngraph TD\n A[\"用户问题\"] --> B[\"Embeddings.search
向量检索\"]\n B --> C[\"获取相关文档\"]\n C --> D[\"组装提示词\"]\n D --> E[\"LLM 生成回答\"]\n E --> F[\"返回结果\"]\n```\n\n资料来源：[examples/rag_quickstart.py:27-38](https://github.com/neuml/txtai/blob/main/examples/rag_quickstart.py)\n\n## API 方法参考\n\n### 核心方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `index(docs)` | list | None | 构建向量索引 |\n| `search(query, limit)` | str, int | list | 执行语义搜索 |\n| `batchindex(docs)` | list | None | 批量构建索引 |\n| `batchsearch(queries, limit)` | list, int | list | 批量搜索 |\n| `save(path)` | str | None | 保存索引到磁盘 |\n| `load(path)` | str | None | 从磁盘加载索引 |\n| `upsert(docs)` | list | None | 更新/插入文档 |\n| `delete(ids)` | list | None | 删除文档 |\n\n### 相似度计算\n\n默认使用余弦相似度进行向量相似度计算，搜索结果按相似度降序排列。分数范围通常为 `[0, 1]`，值越接近 1 表示相似度越高。\n\n## 性能优化建议\n\n1. **批量处理**：使用 `batchindex()` 替代多次 `index()` 调用，减少模型加载开销\n2. **序列长度**：根据实际需求调整 `maxlength`，较短的序列处理速度更快\n3. **GPU 加速**：确保 CUDA 环境配置正确，GPU 模式可显著提升吞吐量\n4. **索引后端选择**：数据量较小时使用 FAISS，超过百万向量时考虑 HNSW\n\n## 与其他系统的比较\n\ntxtai 向量嵌入系统与其他向量数据库的关键差异：\n\n| 特性 | txtai | 专用向量数据库 |\n|------|-------|---------------|\n| 部署复杂度 | 单库部署 | 通常需要独立服务 |\n| 功能范围 | 向量+全文+图谱 | 主要聚焦向量检索 |\n| 集成 LLM | 原生支持 | 需额外集成 |\n| SQL 支持 | 内置 | 部分支持 |\n| 扩展性 | 中等 | 高 |\n\n## 总结\n\ntxtai 的向量嵌入系统提供了一个功能完整、易于使用的语义搜索基础设施。通过模块化的设计，用户可以灵活选择向量模型、索引后端和存储方案。系统与 RAG、工作流引擎、API 服务等组件深度集成，能够支撑从简单语义搜索到复杂 LLM 应用的全场景需求。\n\n---\n\n\n\n## 近似最近邻索引\n\n### 相关页面\n\n相关主题：[向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/ann/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/__init__.py)\n- [src/python/txtai/ann/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/base.py)\n- [src/python/txtai/ann/dense/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/dense/__init__.py)\n- [src/python/txtai/ann/dense/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/ann/dense/factory.py)\n \n\n# 近似最近邻索引\n\n## 概述\n\n近似最近邻索引（Approximate Nearest Neighbor，简称 ANN）是 txtai 语义搜索能力的核心组件。该模块提供了在大规模向量数据中进行高效相似性搜索的功能，通过近似算法在精度和性能之间取得平衡。ANN 索引能够将高维向量映射到低维空间，使得在数百万甚至数十亿向量规模下的最近邻查询成为可能，而无需遍历整个数据集。\n\ntxtai 的 ANN 模块设计遵循模块化架构，支持多种后端实现，包括 Faiss、Annoy、Hnswlib 等主流向量索引库。索引系统与 txtai 的数据管道紧密集成，支持动态构建和增量更新。\n\n## 架构设计\n\n### 核心组件层次\n\n```mermaid\ngraph TD\n A[ANN API] --> B[基类 Ann]\n B --> C[Dense ANN]\n C --> D[Faiss Backend]\n C --> E[Annoy Backend]\n C --> F[Hnswlib Backend]\n C --> G[Scann Backend]\n B --> H[Graph ANN]\n D --> I[IndexFactory]\n```\n\n### 目录结构\n\n```\nsrc/python/txtai/ann/\n├── __init__.py # 模块导出和公共 API\n├── base.py # 基类 Ann 定义\n├── dense/ # 密集向量 ANN 实现\n│ ├── __init__.py\n│ └── factory.py # 索引工厂类\n└── graph/ # 图结构 ANN 实现\n └── __init__.py\n```\n\n资料来源：[src/python/txtai/ann/__init__.py:1-20]()\n\n## 基类设计\n\n### Ann 基类接口\n\n`Ann` 基类定义了所有 ANN 实现必须遵循的统一接口，确保不同后端之间的可替换性。\n\n```python\nclass Ann:\n def __init__(self, path=None, method=None, components=None, **kwargs):\n # 初始化索引配置\n pass\n \n def index(self, documents):\n # 构建索引\n pass\n \n def search(self, query, limit=10):\n # 执行搜索查询\n pass\n \n def load(self, path):\n # 从磁盘加载索引\n pass\n \n def save(self, path):\n # 将索引保存到磁盘\n pass\n```\n\n资料来源：[src/python/txtai/ann/base.py:1-50]()\n\n### 核心方法规范\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `index` | `documents: List[Dict]` | `None` | 构建向量索引 |\n| `search` | `query: ndarray, limit: int` | `List[Tuple[int, float]]` | 搜索最近邻 |\n| `load` | `path: str` | `None` | 加载持久化索引 |\n| `save` | `path: str` | `None` | 保存索引到磁盘 |\n| `reset` | `None` | `None` | 清空索引数据 |\n\n## 密集向量索引\n\n### DenseAnn 实现\n\n`DenseAnn` 类是处理密集向量（dense vectors）的主流实现，支持多种后端算法。\n\n```python\nclass DenseAnn(Ann):\n def __init__(self, path=None, method=None, components=None, **kwargs):\n self.method = method\n self.components = components\n self.ann = None # 后端索引实例\n```\n\n资料来源：[src/python/txtai/ann/dense/__init__.py:1-30]()\n\n### 索引工厂模式\n\n`IndexFactory` 采用工厂模式根据配置动态创建合适的索引后端实例。\n\n```python\nclass IndexFactory:\n @staticmethod\n def create(config):\n method = config.get(\"method\", \"faiss\")\n \n if method == \"faiss\":\n return FaissIndex(config)\n elif method == \"annoy\":\n return AnnoyIndex(config)\n elif method == \"hnsw\":\n return HnswlibIndex(config)\n elif method == \"scann\":\n return ScannIndex(config)\n```\n\n资料来源：[src/python/txtai/ann/dense/factory.py:1-40]()\n\n## 支持的后端算法\n\n### 算法对比\n\n| 后端 | 算法类型 | 优点 | 适用场景 | 内存占用 |\n|------|----------|------|----------|----------|\n| Faiss | IVF-PQ, HNSW | Facebook 出品，成熟稳定 | 大规模生产环境 | 中等 |\n| Annoy | 随机投影树 | 内存高效，支持磁盘加载 | 内存受限环境 | 低 |\n| Hnswlib | HNSW | 查询速度快 | 实时搜索 | 较高 |\n| Scann | ScaNN | Google 出品，精度高 | 高精度需求 | 中等 |\n\n### 配置参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `method` | `str` | `\"faiss\"` | 索引方法 |\n| `components` | `dict` | `None` | 后端特定配置 |\n| `path` | `str` | `None` | 索引文件路径 |\n| `dimensions` | `int` | `None` | 向量维度 |\n| `quantization` | `str` | `None` | 量化类型 (PQ, SQ) |\n\n## 工作流程\n\n### 索引构建流程\n\n```mermaid\ngraph TD\n A[输入文档] --> B[向量化处理]\n B --> C[生成向量数组]\n C --> D[IndexFactory.create]\n D --> E{选择后端}\n E -->|Faiss| F[FaissIndex.index]\n E -->|Annoy| G[AnnoyIndex.index]\n E -->|Hnswlib| H[HnswlibIndex.index]\n F --> I[构建倒排文件]\n G --> J[构建随机树]\n H --> K[构建分层图]\n I --> L[保存索引文件]\n J --> L\n K --> L\n```\n\n### 搜索查询流程\n\n```mermaid\ngraph LR\n A[查询向量] --> B[DenseAnn.search]\n B --> C{选择后端}\n C -->|Faiss| D[nprobe 搜索]\n C -->|Annoy| E[树遍历]\n C -->|Hnswlib| F[图遍历]\n D --> G[返回 Top-K 结果]\n E --> G\n F --> G\n```\n\n## 数据模型\n\n### 索引配置结构\n\n```python\n{\n \"method\": \"faiss\",\n \"components\": {\n \"type\": \"IVF\",\n \"nlist\": 100,\n \"pq\": {\n \"m\": 8,\n \"nbits\": 8\n }\n },\n \"path\": \"/path/to/index\",\n \"dimensions\": 768\n}\n```\n\n### 向量存储格式\n\n| 格式 | 后缀 | 说明 |\n|------|------|------|\n| Faiss Binary | `.bin` | 二进制格式索引文件 |\n| Annoy | `.ann` | Annoy 专有格式 |\n| Hnswlib | `.hnsw` | 分层可导航小世界图 |\n| Scann | `.scann` | Google ScaNN 格式 |\n\n## 集成使用\n\n### 基础用法\n\n```python\nfrom txtai.ann import Ann\n\n# 创建 ANN 索引实例\nann = Ann(method=\"faiss\", dimensions=768)\n\n# 构建索引\ndocuments = [\n {\"id\": 1, \"text\": \"示例文本1\", \"vector\": vector1},\n {\"id\": 2, \"text\": \"示例文本2\", \"vector\": vector2}\n]\nann.index(documents)\n\n# 搜索查询\nresults = ann.search(query_vector, limit=10)\n```\n\n### 与 txtai 管道集成\n\ntxtai 的工作管道自动调用 ANN 模块进行索引和搜索，无需直接操作底层 API。\n\n## 扩展机制\n\n### 自定义后端\n\n开发者可以通过继承 `Ann` 基类实现自定义 ANN 后端：\n\n```python\nclass CustomAnn(Ann):\n def __init__(self, path=None, method=None, **kwargs):\n super().__init__(path, method, **kwargs)\n # 初始化自定义索引\n \n def index(self, documents):\n # 实现索引构建逻辑\n pass\n \n def search(self, query, limit=10):\n # 实现搜索逻辑\n pass\n```\n\n### 注册新后端\n\n在 `IndexFactory` 中注册新的后端类型：\n\n```python\nIndexFactory.register(\"custom\", CustomAnn)\n```\n\n## 性能优化建议\n\n### 索引构建优化\n\n1. **批量索引**：使用批量处理减少索引构建时间\n2. **量化压缩**：启用 PQ 或 SQ 量化以减少内存占用\n3. **分区调整**：合理设置 `nlist` 参数平衡精度与性能\n\n### 查询性能优化\n\n1. **nprobe 调优**：Faiss IVF 索引的 `nprobe` 参数直接影响查询精度和速度\n2. **向量归一化**：对查询向量进行 L2 归一化可提高余弦相似度计算精度\n3. **缓存策略**：对于频繁查询的向量实现结果缓存\n\n## 相关资源\n\n- 官方文档：txtai 语义搜索指南\n- 源码仓库：https://github.com/neuml/txtai\n- 问题反馈：GitHub Issues\n\n---\n\n\n\n## 评分系统\n\n### 相关页面\n\n相关主题：[向量嵌入系统](#page-embeddings)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/scoring/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/__init__.py)\n- [src/python/txtai/scoring/bm25.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/bm25.py)\n- [src/python/txtai/scoring/tfidf.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/tfidf.py)\n- [src/python/txtai/scoring/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/factory.py)\n \n\n# 评分系统\n\n## 概述\n\n评分系统（Scoring System）是 txtai 框架中用于计算文本相似度和相关性的核心组件。该系统提供了 BM25、TF-IDF 等经典信息检索算法实现，并与向量索引、图网络和关系数据库共同构成了 txtai 的**嵌入数据库（Embeddings Database）**基础架构。\n\ntxtai 的评分系统独立于向量搜索模块，专注于传统信息检索评分方法，为混合搜索场景提供稀疏检索能力。\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 系统架构\n\n### 整体架构\n\n评分系统作为 txtai 的可选扩展模块，位于 `txtai.scoring` 包下，采用模块化工厂模式设计。\n\n```mermaid\ngraph TD\n A[评分系统入口] --> B[工厂类 Factory]\n B --> C[BM25 评分器]\n B --> D[TF-IDF 评分器]\n C --> E[SQLAlchemy 存储]\n D --> E\n F[embeddings 配置] --> B\n```\n\n### 依赖关系\n\n评分系统依赖以下核心库：\n\n| 依赖库 | 版本要求 | 用途 |\n|--------|----------|------|\n| SQLAlchemy | ≥2.0.20 | 数据持久化和存储后端 |\n| NumPy | ≥1.18.4 | 数值计算支持 |\n\n资料来源：[setup.py:55](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 核心组件\n\n### 1. BM25 评分器\n\nBM25（Best Matching 25）是基于概率模型的信息检索评分算法，是 Okapi BM25 的标准实现。该算法克服了传统 TF-IDF 在文档长度归一化方面的不足。\n\n**主要特性：**\n- 可调的词项频率饱和度参数（k1）\n- 可调的文档长度归一化参数（b）\n- 基于 IDF（逆文档频率）的词项权重计算\n\n### 2. TF-IDF 评分器\n\nTF-IDF（Term Frequency-Inverse Document Frequency）是经典的文本向量化与评分方法。该评分器将文本集合转换为稀疏向量表示，支持余弦相似度计算。\n\n**主要特性：**\n- 词频统计与归一化\n- 逆文档频率权重计算\n- 稀疏向量输出格式\n\n### 3. 工厂类\n\n工厂类（Factory）负责根据配置创建和管理评分器实例，支持运行时动态选择评分算法。\n\n资料来源：[src/python/txtai/scoring/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/scoring/factory.py)\n\n## 安装配置\n\n### 启用评分系统\n\n通过 pip 安装时指定 scoring 额外依赖：\n\n```bash\npip install txtai[scoring]\n```\n\n此命令将安装核心 txtai 包及评分系统所需的全部依赖。\n\n### setup.py 配置\n\n```python\nextras[\"scoring\"] = [\"sqlalchemy>=2.0.20\"]\n```\n\n资料来源：[setup.py:55](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 与其他模块的集成\n\n### 与 Embeddings 数据库的集成\n\n评分系统是 txtai 嵌入数据库的核心组成部分。根据项目文档，嵌入数据库是以下三者的联合：\n\n```mermaid\ngraph LR\n A[嵌入数据库] --> B[向量索引]\n A --> C[图网络]\n A --> D[关系数据库]\n C --> D\n B --> D\n```\n\n其中，**关系数据库**层集成了评分系统，用于：\n- 存储索引元数据\n- 管理文档映射\n- 执行结构化查询\n\n资料来源：[README.md](https://github.com/neuml/txtai/blob/main/README.md)\n\n### 与相似度搜索的集成\n\n评分系统通过 `ann` 和 `vectors` 组合，构成 `similarity` 额外依赖：\n\n```python\nextras[\"similarity\"] = extras[\"ann\"] + extras[\"vectors\"]\n```\n\n这使得 txtai 能够同时支持：\n- **密集向量搜索**：基于 transformer 模型生成的嵌入向量\n- **稀疏评分搜索**：基于 BM25/TF-IDF 的传统信息检索\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 工作流程\n\n### 索引流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[分词处理]\n B --> C[词项统计]\n C --> D[评分计算]\n D --> E[索引存储]\n```\n\n### 搜索流程\n\n```mermaid\ngraph LR\n A[查询语句] --> B[查询处理]\n B --> C[词项匹配]\n C --> D[相关性评分]\n D --> E[结果排序]\n E --> F[返回 Top-K 结果]\n```\n\n## 配置参数\n\n### BM25 配置项\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| k1 | float | 1.5 | 词项频率饱和度参数 |\n| b | float | 0.75 | 文档长度归一化参数 |\n| avgdl | float | 自动计算 | 平均文档长度 |\n\n### TF-IDF 配置项\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| norm | str | \"l2\" | 向量归一化方式（l1/l2/none） |\n| use_idf | bool | True | 是否启用 IDF 权重 |\n| smooth_idf | bool | True | 是否平滑 IDF |\n\n## 应用场景\n\n### 语义与关键词混合搜索\n\n将密集向量搜索与稀疏评分搜索结合，实现更精确的检索结果：\n\n- **向量搜索**：捕获语义相似性\n- **评分搜索**：精确匹配关键词\n\n### 文档排序与重排序\n\n利用 BM25 或 TF-IDF 分数对候选文档进行重排序，提升最终结果的相关性。\n\n### 知识库检索\n\n作为 RAG（检索增强生成）流程中的检索组件，为大语言模型提供高质量的上下文文档。\n\n## 相关源码文件列表\n\n| 文件路径 | 说明 |\n|----------|------|\n| `src/python/txtai/scoring/__init__.py` | 评分系统包入口，定义公共 API |\n| `src/python/txtai/scoring/bm25.py` | BM25 评分算法实现 |\n| `src/python/txtai/scoring/tfidf.py` | TF-IDF 评分算法实现 |\n| `src/python/txtai/scoring/factory.py` | 评分器工厂类，负责实例创建 |\n\n## 扩展与自定义\n\n开发者可通过继承基类实现自定义评分器：\n\n1. 实现评分计算逻辑\n2. 注册到工厂类\n3. 在 embeddings 配置中指定使用\n\n这种设计允许无缝集成第三方评分算法，满足特定业务场景需求。\n\n---\n\n**注意**：本页面基于 txtai 仓库的 setup.py 配置信息和项目文档生成。详细的 API 使用示例请参考官方示例 notebooks。\n\n---\n\n\n\n## LLM管道\n\n### 相关页面\n\n相关主题：[文本处理管道](#page-pipeline-text), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/llm/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/__init__.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/llm/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/factory.py)\n- [src/python/txtai/pipeline/llm/huggingface.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/huggingface.py)\n- [src/python/txtai/pipeline/llm/rag.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/rag.py)\n \n\n# LLM管道\n\n## 概述\n\nLLM管道是txtai框架中负责与大语言模型（Large Language Model）交互的核心组件。该模块封装了多种语言模型的调用方式，提供了统一的接口来执行文本生成、对话、问答等任务。\n\nLLM管道的主要职责包括：\n\n- **统一抽象**：为不同底层的LLM实现提供一致的API接口\n- **生成控制**：支持流式输出、停止词控制、最大长度限制等生成参数\n- **对话支持**：自动处理聊天模板，支持聊天模型和普通语言模型\n- **多模态扩展**：支持视觉语言模型（VLM）的图像处理能力\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[LLM 基类] --> B[HuggingFace 实现]\n A --> C[LiteLLM 实现]\n A --> D[本地 GGML 实现]\n \n E[LLMFactory] -->|创建| A\n \n F[RAG 模块] -->|使用| A\n \n G[Agent 模块] -->|调用| A\n```\n\n### 模块结构\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `llm.py` | LLM基类，定义通用接口和生成逻辑 |\n| `factory.py` | 工厂类，负责根据配置创建LLM实例 |\n| `huggingface.py` | HuggingFace Transformers后端实现 |\n| `rag.py` | RAG增强生成模块 |\n\n## 核心类详解\n\n### LLM基类\n\nLLM类是所有LLM实现的父类，提供了语言模型调用的通用逻辑。\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/llm.py\nclass LLM:\n def __call__(self, text, maxlength=None, stream=False, stop=None, \n defaultrole=\"auto\", stripthink=None, **kwargs):\n # 核心生成方法\n```\n\n#### 方法说明\n\n| 方法 | 返回类型 | 说明 |\n|------|---------|------|\n| `__call__` | 生成内容 | 执行LLM生成的主要接口 |\n| `ischat` | bool | 判断是否为聊天模型 |\n| `isvision` | bool | 判断是否支持视觉任务 |\n\n#### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `text` | str/list | 必需 | 输入文本，支持字符串或列表 |\n| `maxlength` | int | None | 最大序列长度 |\n| `stream` | bool | False | 是否启用流式输出 |\n| `stop` | list | None | 停止字符串列表 |\n| `defaultrole` | str | \"auto\" | 默认角色（auto/user/prompt） |\n| `stripthink` | bool | None | 是否去除思考标签 |\n\n#### 输入格式支持\n\nLLM管道支持多种输入格式：\n\n1. **字符串或字符串列表**：直接传入文本内容\n2. **字典列表**：遵循聊天模板的role-content格式\n3. **嵌套列表**：二维列表形式的对话历史\n\n```python\n# 示例：不同输入格式\nllm(\"一个简单的问题\") # 字符串\n\nllm([{\"role\": \"user\", \"content\": \"你好\"}]) # 字典列表\n\nllm([[\"user\", \"今天天气如何?\"], [\"assistant\", \"晴天\"]]]) # 嵌套列表\n```\n\n### HuggingFace实现\n\nHuggingFace实现是对Transformers库的直接封装，支持绝大多数HuggingFace模型。\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/huggingface.py\nclass HuggingFace:\n def __call__(self, text, prefix=None, maxlength=512, workers=0, \n stream=False, stop=None, **kwargs):\n```\n\n#### 特殊参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `prefix` | str | None | 添加到文本元素前的前缀 |\n| `workers` | int | 0 | 并发处理的工作线程数 |\n\n#### 任务类型支持\n\nHuggingFace后端支持多种任务类型：\n\n| 任务标识 | 说明 |\n|---------|------|\n| `text2text-generation` | 文本到文本生成（使用SequencesPipeline兼容） |\n| `text-generation` | 标准文本生成 |\n| `summarization` | 摘要生成 |\n| `translation` | 翻译任务 |\n\n## 生成控制\n\n### 流式输出\n\n启用流式输出可以实时获取模型生成的片段：\n\n```python\n# 启用流式输出\nfor chunk in llm(\"写一首诗\", stream=True):\n print(chunk, end=\"\", flush=True)\n```\n\n流式输出会**自动禁用**思考标签去除功能（`stripthink=False`），确保实时显示生成内容。\n\n### 停止词控制\n\n通过`stop`参数可以指定停止条件：\n\n```python\n# 当遇到指定字符串时停止生成\nresult = llm(\"回答以下问题\", stop=[\"\\n\\n\", \"===END===\"])\n```\n\n### 思考标签处理\n\n部分模型会输出XML格式的思考过程，默认行为：\n\n| 模式 | 行为 |\n|------|------|\n| 流式输出（stream=True） | stripthink=False（保留思考内容） |\n| 非流式输出 | stripthink=True（自动去除） |\n\n```python\n# 手动控制思考标签处理\nllm(\"问题\", stripthink=True) # 去除思考标签\nllm(\"问题\", stripthink=False) # 保留思考标签\n```\n\n## RAG增强生成\n\nRAG（检索增强生成）模块将向量检索与LLM生成结合：\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/rag.py\n```\n\n### 工作流程\n\n```mermaid\ngraph LR\n A[用户查询] --> B[向量检索]\n B --> C[相关文档]\n C --> D[构建提示词]\n D --> E[LLM生成]\n E --> F[最终回答]\n```\n\n### 配置示例\n\n```yaml\n# RAG配置示例\nrag:\n embeddings: index.tar\n content: true\n prompt: \"根据以下上下文回答问题：\\n\\n{context}\\n\\n问题：{query}\"\n```\n\n## 工厂模式\n\nLLM工厂类负责根据配置动态创建合适的LLM实例：\n\n```python\n# 资料来源：src/python/txtai/pipeline/llm/factory.py\n```\n\n### 支持的后端类型\n\n| 后端标识 | 说明 |\n|---------|------|\n| `huggingface` | HuggingFace Transformers模型 |\n| `litellm` | LiteLLM统一接口 |\n| `ggml` | 本地GGML/GGUF模型 |\n| `ollama` | Ollama本地服务 |\n| `api` | OpenAI兼容API |\n\n## 使用示例\n\n### 基础文本生成\n\n```python\nfrom txtai.pipeline import LLM\n\n# 创建LLM实例\nllm = LLM(\"meta-llama/Llama-2-7b-chat-hf\")\n\n# 简单生成\nresult = llm(\"解释量子计算的基本原理\")\nprint(result)\n```\n\n### 对话模式\n\n```python\n# 带聊天模板的对话\nmessages = [\n {\"role\": \"system\", \"content\": \"你是一个helpful助手\"},\n {\"role\": \"user\", \"content\": \"什么是向量数据库？\"}\n]\n\nresponse = llm(messages)\nprint(response)\n```\n\n### 带RAG的问答\n\n```python\nfrom txtai.pipeline import RAG\n\n# 创建RAG管道\nrag = RAG({\n \"embeddings\": \"my-index\",\n \"llm\": \"mistralai/Mistral-7B-Instruct-v0.2\"\n})\n\n# 基于检索的问答\nanswer = rag(\"关于项目X的技术细节是什么？\")\n```\n\n## 依赖要求\n\nLLM管道的基础依赖包括：\n\n```python\n# setup.py中的pipeline-llm额外依赖\nextras[\"pipeline-llm\"] = [\n \"httpx>=0.28.1\",\n \"litellm>=1.37.16\",\n \"llama-cpp-python>=0.2.75\"\n]\n```\n\n安装完整LLM支持：\n\n```bash\npip install txtai[pipeline-llm]\n```\n\n## 最佳实践\n\n1. **模型选择**：根据硬件条件选择合适的模型量级\n2. **批处理**：处理大量文本时使用workers参数启用并行\n3. **流式输出**：长文本生成建议启用流式以便及时中断\n4. **停止词**：设置合理的停止条件以控制输出长度\n5. **错误处理**：实现重试机制应对API临时故障\n\n## 相关资源\n\n- [txtai官方文档](https://neuml.github.io/txtai/)\n- [示例笔记本](https://neuml.github.io/txtai/examples)\n- [GitHub仓库](https://github.com/neuml/txtai)\n\n---\n\n\n\n## 文本处理管道\n\n### 相关页面\n\n相关主题：[LLM管道](#page-pipeline-llm), [音频和图像管道](#page-pipeline-audio), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/text/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/__init__.py)\n- [src/python/txtai/pipeline/text/entity.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/entity.py)\n- [src/python/txtai/pipeline/text/labels.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/labels.py)\n- [src/python/txtai/pipeline/text/reranker.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/reranker.py)\n- [src/python/txtai/pipeline/text/summary.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/summary.py)\n- [src/python/txtai/pipeline/llm/llm.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/llm/llm.py)\n- [src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n \n\n# 文本处理管道\n\n文本处理管道（Text Pipeline）是txtai框架中用于处理和分析文本数据的核心组件集合。该管道提供了从文本生成摘要、实体识别、标签分类到结果重排序等完整的自然语言处理能力。\n\n## 概述\n\ntxtai的文本处理管道是一组基于Transformer模型的处理组件，设计用于执行各类文本分析任务。这些管道可以独立使用，也可以组合成复杂的工作流程来处理文本数据。文本处理管道属于txtai的`pipeline-text`扩展模块，需要额外安装相关依赖。\n\n```mermaid\ngraph TD\n A[文本输入] --> B[Summary 摘要生成]\n A --> C[Entity 实体识别]\n A --> D[Labels 标签分类]\n A --> E[Reranker 重排序]\n B --> F[结构化输出]\n C --> F\n D --> F\n E --> G[排序后结果]\n```\n\n## 核心组件\n\n文本处理管道包含以下核心组件：\n\n| 组件名称 | 类名 | 功能描述 |\n|---------|------|---------|\n| 摘要生成 | `Summary` | 从文本生成简洁摘要 |\n| 实体识别 | `Entity` | 识别文本中的命名实体 |\n| 标签分类 | `Labels` | 对文本进行标签分类 |\n| 重排序 | `Reranker` | 对搜索结果进行相关性重排序 |\n\n## 摘要生成（Summary）\n\n### 功能说明\n\n摘要生成管道使用预训练的序列到序列模型将长文本压缩为简洁的摘要内容。该组件支持多种输入格式，可以处理单个文档或批量处理多个文档。\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 模型路径或HuggingFace模型标识符 |\n| `quantize` | bool | False | 是否量化模型 |\n| `gpu` | bool | True | 是否使用GPU |\n| `maxlength` | int | 512 | 生成摘要的最大长度 |\n| `workers` | int | 0 | 并发工作线程数 |\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Summary\n\n# 初始化摘要管道\nsummary = Summary(\"facebook/bart-large-cnn\")\n\n# 生成摘要\ntext = \"\"\"长文本内容...\"\"\"\nresult = summary(text)\n```\n\n资料来源：[src/python/txtai/pipeline/text/summary.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/summary.py)\n\n## 实体识别（Entity）\n\n### 功能说明\n\n实体识别管道用于从文本中提取命名实体及其类型标签。该组件支持两种模式：标准token分类和GLiNER模型。\n\n### GLiNER支持\n\n当检测到使用GLiNER模型时，管道会使用GLiNER库进行实体识别，这提供了更加灵活和高效的实体提取能力。\n\n```python\n# GLiNER实体识别示例\nentity = Entity(\"urchan/gliner_multitask_large-v0.1\")\nentities = entity(\"Apple公司成立于1976年\", labels=[\"组织\", \"日期\"])\n```\n\n### 聚合方法\n\n实体识别支持多种聚合策略来合并多token实体：\n\n| 聚合方法 | 说明 |\n|---------|------|\n| `simple` | 简单合并（默认） |\n| `first` | 取第一个token的分数 |\n| `average` | 取平均分数 |\n| `max` | 取最大分数 |\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 模型路径 |\n| `labels` | list | None | 要识别的实体类型列表 |\n| `aggregate` | str | \"simple\" | 多token实体聚合方法 |\n| `flatten` | bool/float | None | 展平输出，可设置分数阈值 |\n| `join` | bool | False | 是否连接相邻同类型实体 |\n| `workers` | int | 0 | 并发工作线程数 |\n\n资料来源：[src/python/txtai/pipeline/text/entity.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/entity.py)\n\n## 标签分类（Labels）\n\n### 功能说明\n\n标签分类管道用于对文本进行分类标签预测。该组件可以将文本分类为一个或多个预定义的类别标签。\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Labels\n\n# 初始化标签分类器\nlabels = Labels()\n\n# 单标签分类\nresult = labels(\"这部电影非常精彩\", labels=[\"正面\", \"负面\", \"中性\"])\n\n# 多标签分类\nmultilabel = labels(\"新闻内容\", labels=[\"体育\", \"科技\", \"娱乐\"], multi=True)\n```\n\n### 分数阈值\n\n标签分类支持设置分数阈值来过滤低置信度的分类结果：\n\n```python\n# 只返回分数大于0.8的结果\nresult = labels(text, labels=labels_list, threshold=0.8)\n```\n\n资料来源：[src/python/txtai/pipeline/text/labels.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/labels.py)\n\n## 重排序（Reranker）\n\n### 功能说明\n\n重排序管道用于对搜索结果进行相关性重排序。当基础的向量相似度搜索无法完全满足相关性需求时，可以使用重排序模型进行更精确的排序。\n\n### 工作原理\n\n```mermaid\ngraph LR\n A[初始搜索结果] --> B[Reranker模型]\n B --> C[相关性评分]\n C --> D[重排序后的结果]\n```\n\n### 使用示例\n\n```python\nfrom txtai.pipeline import Reranker\n\n# 初始化重排序模型\nreranker = Reranker(\"cross-encoder/ms-marco-MiniLM-L-6-v2\")\n\n# 对搜索结果进行重排序\nquery = \"人工智能应用\"\nresults = [{\"id\": 1, \"text\": \"机器学习技术\"}, {\"id\": 2, \"text\": \"人工智能算法\"}]\nreranked = reranker(query, results)\n```\n\n### API参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| `path` | str | 必需 | 重排序模型路径 |\n| `gpu` | bool | True | 是否使用GPU |\n| `batchsize` | int | 32 | 批处理大小 |\n| `quantize` | bool | False | 是否量化模型 |\n\n资料来源：[src/python/txtai/pipeline/text/reranker.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/text/reranker.py)\n\n## 管道组合使用\n\n文本处理管道可以组合使用以构建复杂的文本分析流程：\n\n```mermaid\ngraph TD\n A[原始文本] --> B[Textractor 文本提取]\n B --> C[Entity 实体识别]\n B --> D[Labels 标签分类]\n C --> E[Summary 摘要生成]\n D --> F[结果合并]\n E --> F\n F --> G[最终输出]\n```\n\n### 工作流集成\n\n在txtai工作流中，文本处理管道可以作为任务节点使用：\n\n```python\nfrom txtai.workflow import Workflow\n\n# 定义工作流\nworkflow = Workflow([\n Textractor(),\n Summary(),\n # 更多处理步骤...\n])\n```\n\n## 依赖项\n\n文本处理管道模块需要以下依赖项：\n\n| 依赖包 | 版本要求 | 说明 |\n|-------|---------|------|\n| gliner | >=0.2.23 | GLiNER实体识别模型 |\n| sentencepiece | >=0.1.91 | 分词工具 |\n| staticvectors | >=0.2.0 | 静态向量模型 |\n| transformers | >=4.56.2 | 核心Transformer库 |\n\n安装所有文本处理依赖：\n\n```bash\npip install txtai[pipeline-text]\n```\n\n资料来源：[setup.py](https://github.com/neuml/txtai/blob/main/setup.py)\n\n## 输入输出格式\n\n### 标准输入格式\n\n文本处理管道支持多种输入格式：\n\n| 格式类型 | 示例 | 说明 |\n|---------|------|------|\n| 字符串 | `\"文本内容\"` | 单个文本 |\n| 字符串列表 | `[\"文本1\", \"文本2\"]` | 批量文本 |\n| 字典列表 | `[{\"text\": \"...\"}]` | 带元数据的文本 |\n\n### 输出格式\n\n处理结果通常以列表或字典格式返回：\n\n```python\n# 实体识别输出示例\n[\n {\"text\": \"Apple\", \"label\": \"组织\", \"score\": 0.95, \"start\": 0, \"end\": 5},\n {\"text\": \"1976年\", \"label\": \"日期\", \"score\": 0.89, \"start\": 15, \"end\": 20}\n]\n\n# 标签分类输出示例\n[(\"正面\", 0.92), (\"中性\", 0.06), (\"负面\", 0.02)]\n```\n\n## 最佳实践\n\n### 性能优化\n\n1. **批量处理**：使用批量输入可以显著提高处理速度\n2. **GPU加速**：确保CUDA环境正确配置以启用GPU加速\n3. **模型量化**：对于大模型，使用量化可以减少内存占用\n\n### 准确性提升\n\n1. 选择与任务领域匹配的专业模型\n2. 合理设置标签列表和分数阈值\n3. 结合多种管道组件进行综合分析\n\n### 错误处理\n\n```python\ntry:\n result = pipeline(input_text)\nexcept Exception as e:\n logger.error(f\"处理失败: {e}\")\n # 降级处理或返回默认值\n```\n\n## 扩展文本管道\n\n开发者可以通过继承基础管道类来创建自定义文本处理组件：\n\n```python\nfrom txtai.pipeline import HFPipeline\n\nclass CustomTextProcessor(HFPipeline):\n def __init__(self, path=None, quantize=False, gpu=True, **kwargs):\n super().__init__(\"text-classification\", path, quantize, gpu, **kwargs)\n \n def __call__(self, text, **kwargs):\n # 自定义处理逻辑\n return super().__call__(text, **kwargs)\n```\n\n资料来源：[src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n\n---\n\n\n\n## 音频和图像管道\n\n### 相关页面\n\n相关主题：[文本处理管道](#page-pipeline-text), [工作流引擎](#page-workflow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/pipeline/audio/transcription.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/audio/transcription.py)\n- [src/python/txtai/pipeline/audio/texttoaudio.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/audio/texttoaudio.py)\n- [src/python/txtai/pipeline/data/textractor.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/data/textractor.py)\n- [src/python/txtai/pipeline/image/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/image/__init__.py)\n- [src/python/txtai/pipeline/image/caption.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/image/caption.py)\n- [src/python/txtai/pipeline/hfpipeline.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/pipeline/hfpipeline.py)\n \n\n# 音频和图像管道\n\n## 概述\n\ntxtai 的音频和图像管道是框架多媒体处理能力的核心组成部分，分别位于 `txtai.pipeline.audio` 和 `txtai.pipeline.image` 模块中。这些管道支持从音频文件中提取文本内容（语音转文本），以及从文本生成音频（文本转语音）和图像描述（图像字幕生成）。\n\n音频管道基于 Hugging Face Transformers 框架构建，通过 `HFPipeline` 基类提供统一的接口。图像管道同样继承自 `HFPipeline`，使用计算机视觉模型处理图像数据。两者都支持 GPU 加速和模型量化，能够处理单个文件或批量数据。\n\n## 音频管道\n\n### 架构设计\n\n音频管道采用模块化设计，主要包含两个核心组件：\n\n```mermaid\ngraph TD\n A[音频输入] --> B{数据类型判断}\n B -->|文件路径| C[FileToHTML/直接加载]\n B -->|原始音频数据| D[Signal处理模块]\n C --> E[Transcription管道]\n D --> E\n E --> F[Speech Recognition Pipeline]\n F --> G[转录文本输出]\n```\n\n### Transcription 模块\n\n`Transcription` 类负责将音频内容转录为文本。该模块支持两种后端实现：当 `scipy` 和 `soundfile` 库可用时，使用本地信号处理；否则回退到其他可用方案。资料来源：[transcription.py:1-20]()\n\n```python\nclass Transcription(HFPipeline):\n \"\"\"\n Transcribes audio files or data to text.\n \"\"\"\n```\n\n#### 核心参数说明\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| path | str | 模型路径或 Hugging Face 模型标识符 | None |\n| quantize | bool | 是否量化模型以减少内存占用 | False |\n| gpu | bool | 是否使用 GPU 进行推理 | True |\n| model | str | 指定具体模型变体 | None |\n\n#### 主要方法\n\n`__call__(audio, rate=None, chunk=10, join=True, **kwargs)` 方法是 Transcription 的核心接口：\n\n```python\ndef __call__(self, audio, rate=None, chunk=10, join=True, **kwargs):\n \"\"\"\n Transcribes audio files or data to text.\n\n Args:\n audio: audio|list\n rate: sample rate, only required with raw audio data\n chunk: process audio in chunk second sized segments\n join: if True (default), combine each chunk back together into a single text output.\n When False, chunks are returned as a list of dicts, each having raw associated audio and\n sample rate in addition to text\n \"\"\"\n```\n\n该方法支持三种处理模式：\n\n- **完整转录**：设置 `chunk=0` 可对整个音频文件进行一次性处理\n- **分段转录**：设置 `chunk` 值（秒）可按指定时长分段处理长音频\n- **批量转录**：传入音频列表可并行处理多个文件\n\n#### 输入输出格式\n\n| 输入类型 | 输入示例 | 输出类型 | 输出示例 |\n|----------|----------|----------|----------|\n| 单个音频文件路径 | `\"/path/to/audio.wav\"` | str | `\"转录的文本内容\"` |\n| 音频文件列表 | `[\"file1.wav\", \"file2.wav\"]` | list | `[\"文本1\", \"文本2\"]` |\n| 原始音频数据 | `(numpy数组, 采样率)` | str/list | 根据输入格式确定 |\n\n### TextToAudio 模块\n\n`TextToAudio` 类执行相反的操作，将文本内容转换为语音音频。该模块继承自 `HFPipeline`，使用 text-to-speech 模型生成音频波形。资料来源：[texttoaudio.py:1-30]()\n\n```python\nclass TextToAudio(HFPipeline):\n \"\"\"\n Generates audio from text.\n \"\"\"\n```\n\n#### 参数配置\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| path | str | TTS 模型路径 | None |\n| quantize | bool | 量化模型 | False |\n| gpu | bool | GPU 加速 | True |\n| model | str | 模型标识符 | None |\n| rate | int | 目标采样率 | None（使用模型默认采样率） |\n\n#### 工作流程\n\n```mermaid\ngraph LR\n A[输入文本] --> B[TextToAudio Pipeline]\n B --> C[generate audio]\n C --> D{rate 参数设置?}\n D -->|是| E[重采样到目标采样率]\n D -->|否| F[使用模型原生采样率]\n E --> G[(音频输出)]\n F --> G\n```\n\n#### 音频转换处理\n\n当设置 `rate` 参数时，`convert` 方法会执行采样率转换：\n\n```python\ndef convert(self, result):\n \"\"\"\n Converts audio result to target sample rate for this pipeline, if set.\n\n Args:\n result: dict with audio samples and sample rate\n\n Returns:\n audio with converted sample rate\n \"\"\"\n```\n\n返回格式为元组 `(audio_data, sample_rate)`，可直接用于音频播放或保存。\n\n## 图像管道\n\n### ImageCaption 模块\n\n`ImageCaption` 类使用计算机视觉模型为图像生成描述性文本。该模块同样继承自 `HFPipeline`，使用图像字幕生成模型。资料来源：[caption.py]()\n\n```python\nclass ImageCaption(HFPipeline):\n \"\"\"\n Image captioning pipeline that generates descriptions for images.\n \"\"\"\n```\n\n### 图像处理流程\n\n```mermaid\ngraph TD\n A[图像输入] --> B{输入类型判断}\n B -->|URL| C[HTTP 请求获取]\n B -->|文件路径| D[本地文件读取]\n B -->|PIL Image| E[直接处理]\n B -->|Base64| F[解码处理]\n C --> G[图像预处理]\n D --> G\n E --> G\n F --> G\n G --> H[Vision Transformer 模型]\n H --> I[生成字幕/描述]\n I --> J[文本输出]\n```\n\n## 统一 API 接口\n\n所有管道都遵循统一的调用约定，简化了多模态处理的复杂性：\n\n### HFPipeline 基类\n\n音频和图像管道都继承自 `HFPipeline` 基类，该基类提供：\n\n- 统一的模型加载和缓存机制\n- GPU/CPU 自动检测和设备分配\n- 批量处理支持\n- 流式输出支持（部分管道）\n\n### 通用参数\n\n| 参数 | 说明 | 适用管道 |\n|------|------|----------|\n| path | 模型路径或 Hugging Face 模型 ID | 所有管道 |\n| quantize | 启用 4-bit/8-bit 量化 | 所有管道 |\n| gpu | 启用 GPU 推理 | 所有管道 |\n| model | 指定具体模型配置 | 所有管道 |\n\n## 依赖要求\n\n音频和图像管道需要安装特定的依赖包。通过 `pipeline-audio` 和 `pipeline-image` extras 可一键安装：\n\n```bash\npip install txtai[pipeline-audio]\npip install txtai[pipeline-image]\n```\n\n### 音频管道依赖\n\n根据 `setup.py` 配置：\n\n```python\nextras[\"pipeline-audio\"] = [\n \"onnx>=1.11.0\",\n \"onnxruntime>=1.11.0\",\n \"scipy>=1.4.1\",\n \"sounddevice>=0.5.0\",\n \"soundfile>=0.10.3.post1\",\n \"ttstokenizer>=1.1.0\",\n \"webrtcvad-wheels>=2.0.14\",\n]\n```\n\n### 图像管道依赖\n\n```python\nextras[\"pipeline-image\"] = [\n \"imagehash>=4.2.1\",\n \"pillow>=7.1.2\",\n \"timm>=0.4.12\",\n]\n```\n\n## 实际应用示例\n\n### 音频转录\n\n```python\nfrom txtai.pipeline import Transcription\n\n# 初始化转录管道\ntranscribe = Transcription(\"facebook/wav2vec2-base-960h\")\n\n# 单个文件转录\ntext = transcribe(\"/path/to/audio.wav\")\n\n# 分段处理长音频（每段30秒）\ntext = transcribe(\"/path/to/long_audio.wav\", chunk=30)\n\n# 批量处理\ntexts = transcribe([\"file1.wav\", \"file2.wav\"])\n```\n\n### 文本转语音\n\n```python\nfrom txtai.pipeline.audio import TextToAudio\n\n# 初始化 TTS 管道\ntts = TextToAudio(\"facebook/fastspeech2-en-ljspeech\")\n\n# 生成音频\naudio, rate = tts(\"Hello, this is a text to speech conversion.\")\n\n# 指定采样率\naudio, rate = tts(\"Custom sample rate audio\", rate=22050)\n```\n\n## 工作流集成\n\n音频和图像管道可以无缝集成到 txtai 的工作流系统中，支持复杂的多模态处理流程：\n\n```python\nfrom txtai import Workflow\n\n# 创建包含音频处理的工作流\nworkflow = Workflow([\n {\"action\": \"transcription\", \"task\": \"audio\"},\n {\"action\": \"translation\", \"task\": \"text\"},\n])\n```\n\n## 最佳实践\n\n1. **模型选择**：根据精度和速度需求选择合适的预训练模型\n2. **GPU 加速**：处理大量数据时启用 GPU 以提升性能\n3. **批量处理**：使用列表输入进行批量处理，提高吞吐量\n4. **内存管理**：长音频文件使用分段处理避免内存溢出\n5. **采样率配置**：确保输出音频采样率符合目标应用需求\n\n## 总结\n\ntxtai 的音频和图像管道提供了强大且统一的多媒体处理能力。通过继承 `HFPipeline` 基类，这些管道实现了标准化的接口和一致的配置方式。Transcription 支持灵活的音频转文本处理，TextToAudio 提供文本到语音的生成能力，ImageCaption 则实现图像描述生成。这些组件可以独立使用，也可以集成到更复杂的工作流中，支持端到端的多模态 AI 应用开发。\n\n---\n\n\n\n## 工作流引擎\n\n### 相关页面\n\n相关主题：[核心组件](#page-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/python/txtai/workflow/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/__init__.py)\n- [src/python/txtai/workflow/base.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/base.py)\n- [src/python/txtai/workflow/factory.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/factory.py)\n- [src/python/txtai/workflow/task/__init__.py](https://github.com/neuml/txtai/blob/main/src/python/txtai/workflow/task/__init__.py)\n \n\n# 工作流引擎\n\n## 概述\n\ntxtai 工作流引擎是一个强大的组件编排框架，用于构建复杂的数据处理管道。它允许用户将多个处理组件（如文本提取、摘要生成、翻译等）串联成可配置的工作流程，支持并行处理、并发执行、结果合并等高级功能。\n\n工作流引擎的核心设计理念是**声明式任务编排**：用户通过定义任务列表来描述数据处理流程，系统自动管理任务间的数据传递和执行顺序。\n\n## 核心架构\n\n### 组件层次结构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Workflow │\n│ ┌───────────────────────────────────────────────────────┐ │\n│ │ Task[] │ │\n│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │\n│ │ │ Task 1 │→ │ Task 2 │→ │ Task 3 │→ │ Task N │ │ │\n│ │ │(动作函数)│ │(动作函数)│ │(动作函数)│ │(动作函数)│ │ │\n│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │\n│ └───────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ ┌───────────────────────────────────────────────────────┐ │\n│ │ 任务基类 (Task Base) │ │\n│ │ - action: 处理动作 │ │\n│ │ - select: 数据过滤器 │ │\n│ │ - initialize/finalize: 生命周期钩子 │ │\n│ └───────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 核心类说明\n\n| 类名 | 文件位置 | 功能描述 |\n|------|----------|----------|\n| Workflow | workflow/__init__.py | 工作流主控制器，管理任务执行流程 |\n| Task | workflow/task/base.py | 任务基类，定义任务通用接口 |\n| TemplateTask | workflow/task/template.py | 模板任务，支持 prompt 模板化处理 |\n\n## 工作流执行模型\n\n### 数据处理流程\n\n```mermaid\ngraph LR\n A[输入数据] --> B[Task 1]\n B --> C[Task 2]\n C --> D[Task 3]\n D --> E[输出结果]\n \n F[初始化动作] -.-> A\n E -.-> G[最终化动作]\n```\n\n### 并发处理模型\n\n```mermaid\ngraph TD\n subgraph 并发模式\n A[输入列表] --> B{并发方式}\n B -->|Thread| C[线程池执行]\n B -->|Process| D[进程池执行]\n B -->|默认| E[顺序执行]\n end\n \n C --> F[结果聚合]\n D --> F\n E --> F\n```\n\n## Task 基类详解\n\n### 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| action | callable/list | [] | 要执行的处理动作 |\n| select | callable/list | None | 数据过滤选择器 |\n| unpack | bool | True | 是否解包数据元组 |\n| column | int | None | 选择元组的列索引 |\n| merge | str | \"hstack\" | 多动作输出合并模式 |\n| initialize | callable | None | 执行前初始化动作 |\n| finalize | callable | None | 执行后终结动作 |\n| concurrency | str | None | 并发方式 (\"thread\"/\"process\") |\n| onetomany | bool | True | 启用一对多转换 |\n\n### 核心方法\n\n```python\ndef __init__(\n self,\n action=None,\n select=None,\n unpack=True,\n column=None,\n merge=\"hstack\",\n initialize=None,\n finalize=None,\n concurrency=None,\n onetomany=True,\n **kwargs,\n)\n```\n\n**生命周期钩子**：\n\n- **initialize**: 在处理开始前执行，常用于加载模型、资源初始化\n- **finalize**: 在处理结束后执行，常用于资源释放、结果后处理\n\n资料来源：[src/python/txtai/workflow/task/base.py:22-50]()\n\n## 模板任务 (TemplateTask)\n\nTemplateTask 继承自 Task 基类，专门用于生成 LLM 提示词模板。\n\n### 模板处理规则\n\n```mermaid\ngraph TD\n A[输入数据] --> B{数据类型判断}\n B -->|dict| C[作为命名参数传入]\n B -->|tuple| D[映射为 arg0-argN]\n B -->|其他| E[作为 {text} 参数]\n \n C --> F[TemplateFormatter 格式化]\n D --> F\n E --> F\n F --> G[渲染后的模板字符串]\n```\n\n### 模板注册方法\n\n```python\ndef register(self, template=None, rules=None, strict=True):\n # template: 提示词模板文本\n # rules: 参数处理规则\n # strict: 是否要求所有输入被模板消费\n```\n\n支持的模板参数注入方式：\n\n| 输入类型 | 处理方式 | 示例 |\n|----------|----------|------|\n| dict | 展开为命名参数 | `{\"topic\": \"AI\", \"length\": 100}` |\n| tuple | 映射为 arg0-argN | `(\"AI\", 100)` → arg0=\"AI\", arg1=100 |\n| 其他 | 作为 {text} 参数 | `input` → {text}=input |\n\n资料来源：[src/python/txtai/workflow/task/template.py:10-45]()\n\n## 工作流构建示例\n\n### 基础使用模式\n\n```python\nfrom txtai import Workflow\nfrom txtai.pipeline import Summary, Textractor, Translation\nfrom txtai.workflow import Task\n\n# 步骤1: 定义处理管道\ntextractor = Textractor(backend=\"docling\", headers={\"user-agent\": \"Mozilla/5.0\"})\nsummary = Summary()\ntranslate = Translation()\n\n# 步骤2: 构建工作流\nworkflow = Workflow([\n Task(textractor), # 提取文本\n Task(summary), # 生成摘要\n Task(lambda inputs: [translate(x, \"fr\") for x in inputs]) # 翻译\n])\n\n# 步骤3: 执行工作流\nresults = list(workflow([\"https://example.com/article\"]))\n```\n\n### 使用 LLM 完成任务\n\n```python\nfrom txtai import LLM, Workflow\nfrom txtai.pipeline import Textractor\nfrom txtai.workflow import Task\n\ntextractor = Textractor(backend=\"docling\")\nllm = LLM(\"Qwen/Qwen3-4B-Instruct\")\n\nworkflow = Workflow([\n Task(textractor),\n Task(lambda inputs: llm([f\"Summarize in 40 words: {x}\" for x in inputs]))\n])\n\nlist(workflow([\"https://example.com\"]))\n```\n\n资料来源：[examples/workflow_quickstart.py:1-45]()\n\n## 内置任务类型\n\n### UrlTask\n\n专门用于处理 URL 链接的预配置任务，自动调用 Textractor 进行内容提取。\n\n```python\nfrom txtai.workflow import UrlTask, Task, Workflow\nfrom txtai.pipeline import Textractor, Summary\n\nworkflow = Workflow([\n UrlTask(Textractor(paragraphs=True, minlength=100, join=True)),\n Task(Summary(\"sshleifer/distilbart-cnn-12-6\"))\n])\n\n# 处理 URL\nurl = \"https://neuml.com\"\nsummary = list(workflow([url]))[0]\n```\n\n### 任务组合模式\n\n| 组合方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| 顺序执行 | 任务列表按顺序传递 | 管道式处理 |\n| 并行执行 | concurrency=\"thread\"/\"process\" | CPU/IO 密集型任务 |\n| 一对多 | onetomany=True | 数据分割/扩展 |\n\n资料来源：[examples/article.py:1-55]()\n\n## 工作流配置\n\n### 依赖项配置\n\n工作流引擎通过 setup.py 管理可选依赖：\n\n```python\nextras[\"workflow\"] = [\n \"apache-libcloud>=3.3.1\",\n \"croniter>=1.2.0\",\n \"openpyxl>=3.0.9\",\n \"pandas>=1.1.0\",\n \"pillow>=7.1.2\",\n \"requests>=2.26.0\",\n \"xmltodict>=0.12.0\",\n]\n```\n\n### 安装方式\n\n```bash\n# 基础安装\npip install txtai\n\n# 包含工作流依赖\npip install txtai[workflow]\n```\n\n## 高级特性\n\n### 数据选择与过滤\n\n```python\n# 使用 select 参数过滤数据\nworkflow = Workflow([\n Task(action=processor, select=lambda x: x.get(\"valid\")),\n])\n```\n\n### 结果合并策略\n\n| 合并模式 | 说明 |\n|----------|------|\n| hstack | 水平堆叠（默认） |\n| 自定义 | 通过 merge 参数指定合并函数 |\n\n### 生命周期管理\n\n```python\ndef init_model():\n \"\"\"初始化动作 - 加载模型\"\"\"\n return load_heavy_model()\n\ndef cleanup(results):\n \"\"\"终结动作 - 清理资源\"\"\"\n return post_process(results)\n\nworkflow = Workflow([\n Task(action=process, initialize=init_model, finalize=cleanup)\n])\n```\n\n## 最佳实践\n\n### 性能优化建议\n\n1. **合理选择并发模式**：CPU 密集型用 \"process\"，IO 密集型用 \"thread\"\n2. **减少不必要的数据转换**：使用 unpack=False 保持数据格式\n3. **使用缓存**：对于重复执行的工作流，考虑缓存模型加载\n\n### 错误处理\n\n```python\nworkflow = Workflow([\n Task(action=risky_processor),\n Task(action=fallback_processor), # 异常时使用后备方案\n])\n```\n\n### 与 LLM 集成\n\n工作流引擎是构建 RAG（检索增强生成）管道的基础组件：\n\n```mermaid\ngraph LR\n A[文档] --> B[Textractor]\n B --> C[分割器]\n C --> D[Embedding]\n D --> E[(向量数据库)]\n E --> F[检索]\n F --> G[LLM 生成]\n```\n\n## 总结\n\ntxtai 工作流引擎提供了灵活、高效的组件编排能力，其核心特点包括：\n\n- **声明式配置**：通过任务列表声明处理流程\n- **丰富的数据转换**：支持多种数据格式和合并策略\n- **生命周期管理**：initialize/finalize 钩子支持资源管理\n- **并发执行**：支持线程和进程两种并发模式\n- **与 LLM 深度集成**：可无缝连接语言模型处理\n\n工作流引擎是构建复杂 AI 应用的核心基础设施，特别适用于文档处理管道、RAG 系统和多阶段数据处理场景。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：neuml/txtai\n\n摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add `txtai_minimal` package。\n\n## 1. 安装坑 · 来源证据：Add `txtai_minimal` package\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add `txtai_minimal` package\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e4050b59fdf4d51ac21e82d248e589e | https://github.com/neuml/txtai/issues/1090 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Add custom Captions implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Captions implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff6fe05065564e85a549d7656b85a852 | https://github.com/neuml/txtai/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Add custom Questions pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Questions pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa68ea29089d497bb8278c3c360c363c | https://github.com/neuml/txtai/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Add custom Sequences pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Sequences pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0099afb385ef498d8020521bbf3e9e64 | https://github.com/neuml/txtai/issues/1086 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Add custom Summary pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Summary pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d8f75c31fc6450d8659b310f25d0bf4 | https://github.com/neuml/txtai/issues/1085 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Add minimal Docker build script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add minimal Docker build script\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38e1e56a991b412bbc749d2c0b687d54 | https://github.com/neuml/txtai/issues/1092 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Make `transformers` package optional for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Make `transformers` package optional for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d755829200de4d93b2f4d2f71b36aaf1 | https://github.com/neuml/txtai/issues/1091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Reduce dependencies to just `numpy` for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Reduce dependencies to just `numpy` for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_395b735968ab4ec8ad849070d43cd18f | https://github.com/neuml/txtai/issues/1093 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：Support minimal install for edge devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support minimal install for edge devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec8e039baf4412888ed3ac543ea1361 | https://github.com/neuml/txtai/issues/1089 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Various training pipeline fixes for v5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Various training pipeline fixes for v5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b47325d7496248a993d980c3d59f3269 | https://github.com/neuml/txtai/issues/1088 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：Zero dependency minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Zero dependency minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7839a465e7e64f94acfff001c1da978c | https://github.com/neuml/txtai/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v9.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v9.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b842ce68a1c4c1ab0a40a3ed1fd213c | https://github.com/neuml/txtai/releases/tag/v9.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:286301447 | https://github.com/neuml/txtai | README/documentation is current enough for a first validation pass.\n\n## 14. 运行坑 · 来源证据：v9.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v9.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3f61e41f6e84b9b9ee33d5e18dbff63 | https://github.com/neuml/txtai/releases/tag/v9.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：Add LiteRT-LM LLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add LiteRT-LM LLM\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8731971fd8404df082f75ecf565fef8b | https://github.com/neuml/txtai/issues/1095 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v9.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.6.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe429d6152304930bda149c4fbd35318 | https://github.com/neuml/txtai/releases/tag/v9.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v9.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bebd6701b454baaae22d73522ce9704 | https://github.com/neuml/txtai/releases/tag/v9.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：neuml/txtai\n\n摘要：发现 22 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add `txtai_minimal` package。\n\n## 1. 安装坑 · 来源证据：Add `txtai_minimal` package\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add `txtai_minimal` package\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e4050b59fdf4d51ac21e82d248e589e | https://github.com/neuml/txtai/issues/1090 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Add custom Captions implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Captions implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff6fe05065564e85a549d7656b85a852 | https://github.com/neuml/txtai/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Add custom Questions pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Questions pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fa68ea29089d497bb8278c3c360c363c | https://github.com/neuml/txtai/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Add custom Sequences pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Sequences pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0099afb385ef498d8020521bbf3e9e64 | https://github.com/neuml/txtai/issues/1086 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：Add custom Summary pipeline implementation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add custom Summary pipeline implementation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9d8f75c31fc6450d8659b310f25d0bf4 | https://github.com/neuml/txtai/issues/1085 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：Add minimal Docker build script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add minimal Docker build script\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_38e1e56a991b412bbc749d2c0b687d54 | https://github.com/neuml/txtai/issues/1092 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Make `transformers` package optional for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Make `transformers` package optional for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d755829200de4d93b2f4d2f71b36aaf1 | https://github.com/neuml/txtai/issues/1091 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：Reduce dependencies to just `numpy` for minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Reduce dependencies to just `numpy` for minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_395b735968ab4ec8ad849070d43cd18f | https://github.com/neuml/txtai/issues/1093 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：Support minimal install for edge devices\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support minimal install for edge devices\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ec8e039baf4412888ed3ac543ea1361 | https://github.com/neuml/txtai/issues/1089 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Various training pipeline fixes for v5\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Various training pipeline fixes for v5\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b47325d7496248a993d980c3d59f3269 | https://github.com/neuml/txtai/issues/1088 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 安装坑 · 来源证据：Zero dependency minimal install\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Zero dependency minimal install\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7839a465e7e64f94acfff001c1da978c | https://github.com/neuml/txtai/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 安装坑 · 来源证据：v9.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v9.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b842ce68a1c4c1ab0a40a3ed1fd213c | https://github.com/neuml/txtai/releases/tag/v9.9.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 13. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:286301447 | https://github.com/neuml/txtai | README/documentation is current enough for a first validation pass.\n\n## 14. 运行坑 · 来源证据：v9.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v9.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3f61e41f6e84b9b9ee33d5e18dbff63 | https://github.com/neuml/txtai/releases/tag/v9.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | last_activity_observed missing\n\n## 16. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:286301447 | https://github.com/neuml/txtai | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：Add LiteRT-LM LLM\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add LiteRT-LM LLM\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8731971fd8404df082f75ecf565fef8b | https://github.com/neuml/txtai/issues/1095 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v9.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.6.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe429d6152304930bda149c4fbd35318 | https://github.com/neuml/txtai/releases/tag/v9.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：v9.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v9.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8bebd6701b454baaae22d73522ce9704 | https://github.com/neuml/txtai/releases/tag/v9.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:286301447 | https://github.com/neuml/txtai | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# txtai - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 txtai 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: 💡 All-in-one AI framework for semantic search, LLM orchestration and language model workflows 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：txtai概述。围绕“txtai概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n4. page-embeddings：向量嵌入系统。围绕“向量嵌入系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-pipeline-llm：LLM管道。围绕“LLM管道”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“txtai概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-embeddings\n输入：用户提供的“向量嵌入系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-pipeline-llm\n输入：用户提供的“LLM管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“txtai概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-components：Step 3 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-embeddings：Step 4 必须围绕“向量嵌入系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-pipeline-llm：Step 5 必须围绕“LLM管道”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/neuml/txtai\n- https://github.com/neuml/txtai#readme\n- README.md\n- src/python/txtai/__init__.py\n- src/python/txtai/embeddings/base.py\n- src/python/txtai/workflow/base.py\n- src/python/txtai/agent/base.py\n- src/python/txtai/embeddings/__init__.py\n- src/python/txtai/pipeline/__init__.py\n- src/python/txtai/workflow/__init__.py\n- src/python/txtai/agent/__init__.py\n- src/python/txtai/embeddings/index/__init__.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 txtai 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：neuml/txtai\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install txtai\n```\n\n来源：https://github.com/neuml/txtai#readme\n\n## 来源\n\n- repo: https://github.com/neuml/txtai\n- docs: https://github.com/neuml/txtai#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_0113bd6941264ce5bd0bac2c55fff767"
}