Практичні примітки: PageIndex: Фреймворк RAG, який витіснив векторні бази даних
Покрокове пояснення до практичних нотаток: PageIndex: Фреймворк RAG, який витіснив векторні бази даних: контракти, перевірки та готові блоки коду для команд, які використовують цю модель.
Використовуйте цей документ як оновлену версію ідей з статті “PageIndex: The RAG Framework That Threw Out Vector Databases and Still Hit 98.7% Accuracy”, орієнтовану на операторів: чіткі етапи, впорядковані блоки коду та примітки щодо відновлення, які залишаються при передачі обов’язків.
Як система пошуку на основі міркувань VectifyAI тихо руйнує найглибше укорінене припущення в промислових RAG-системах
Етап міркувань у VectifyAI працює найкраще, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Видимість витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ. Визначте бюджет на токени за кожен раунд та сеанс. Інструменти типу агентів активно розширюють контекст; жорсткі обмеження запобігають тому, щоб демо-версії перетворювалися на несподівані рахунки.
Проблему, яку ми постійно ігноруємо
Підхід «Проблема, яку ми постійно вирішуємо» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний зразок роботи, один випадок невдачі та примітки щодо скасування змін перед розширенням обсягу роботи. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Розділіть політику часткової обробки даних від політики їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.
Що насправді є PageIndex
Етап «Що насправді є PageIndex» найкраще функціонує, якщо його розглядати як вимірювану характеристику. Запишіть один ідеальний приклад роботи, один випадок збою та примітки щодо скасування змін перед розширенням обсягу. Документуйте як успішний, так і відновлювальний сценарії роботи разом. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Розділіть політику часткової обробки даних від політики їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.
Крок 1: Створення ієрархічного деревоподібного індексу
Крок 1 «Створення сцени» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Зафіксуйте один ідеальний результат, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Розділяйте політику часткового оброблення даних та політику їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.
{
"node_id": "0006",
"title": "Financial Stability",
"start_index": 21,
"end_index": 22,
"summary": "Covers the Federal Reserve's financial stability oversight...",
"sub_nodes": [
{
"node_id": "0007",
"title": "Monitoring Financial Vulnerabilities",
"start_index": 22,
"end_index": 28,
"summary": "Describes the Fed's vulnerability monitoring framework..."
},
{
"node_id": "0008",
"title": "Domestic and International Cooperation",
"start_index": 28,
"end_index": 31,
"summary": "Federal Reserve collaboration with international bodies..."
}
]
}
Крок 2: Пошук у дереві на основі логічних міркувань
Етап „Дерево, засноване на міркуваннях“, крок 2, працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Встановіть ліміти на кількість токенів за хід та за сеанс. Інструменти типу агентів активно розширюють контекст; жорсткі обмеження запобігають тому, що демонстрації перетворюються на несподівані рахунки. Етап „Дерево, засноване на міркуваннях“, крок 2, працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Зберігайте конфігурацію поза кодом програми. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф.
Чому це справді ефективно: приклад з Додатку G
На етапі «Чому це насправді працює» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Наводьте цитати з тих частин тексту, які фактично підтримують вашу відповідь. Без цитат оператори не зможуть відрізнити галюцинації від проблем з індексуванням.
Реалізація на Python: End-to-End Vectorless RAG
Для етапу без векторів у реалізації на Python необхідно визначити вхідні дані, відповідального за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, тестирувані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Розділіть процес створення клієнта від циклу обробки повідомлень, щоб можна було замінювати постачальників без переписування машини станів розмови.
Встановлення
На етапі встановлення необхідно визначити вхідні дані, виконавця кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безповідомного часткового завершення. Наводьте конкретні уривки, які лежать в основі відповіді. Без посилань оператори не зможуть відрізнити галюцинацію від проблем із індексуванням.
pip install pageindex openai
Налаштування
На етапі налаштування необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке відображення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-середовища до спільних. Наводьте конкретні уривки тексту, які лягли в основу відповіді. Без посилань оператори не зможуть відрізнити галюцинації від проблем з індексуванням.
import os
import json
import asyncio
from pageindex import PageIndexClient
from openai import AsyncOpenAI
# Grab an API key from https://dash.pageindex.ai/api-keys
PAGEINDEX_API_KEY = os.environ["PAGEINDEX_API_KEY"]
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]pi_client = PageIndexClient(api_key=PAGEINDEX_API_KEY)
openai_client = AsyncOpenAI(api_key=OPENAI_API_KEY)
Завантажте документ та створіть дерево
Для функцій «Прийняття документа» та «Стадіювання» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь алгоритм. Необхідно наводити конкретні уривки тексту, які лягли в основу відповіді. Без посилань оператори не зможуть відрізнити галюцинації від проблем із індексуванням.
import pageindex.utils as utils
# Upload a PDF; PageIndex handles the tree generation
doc = pi_client.upload("annual_report_2024.pdf")
doc_id = doc["doc_id"]# Tree generation takes a bit, so we poll
while not pi_client.is_retrieval_ready(doc_id):
print("Still indexing...")
import time; time.sleep(5)# Grab the tree and take a look
tree = pi_client.get_tree(doc_id, node_summary=True)["result"]
print("Document Tree:")
utils.print_tree(tree)
Основа: пошук у дереві за допомогою LLM
Для етапу The Core LLM-Driven Tree необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. У разі, коли наступним кроком є код або виклик інструменту, краще використовувати структуровані результати з перевіркою схеми, ніж вільний текст.
async def find_relevant_nodes(tree: dict, query: str) -> list:
"""LLM reasons over tree structure to identify relevant nodes."""
# Strip raw text to save tokens; the LLM only needs titles and summaries
tree_without_text = utils.remove_fields(
tree.copy(), fields=["text"]
) search_prompt = f"""
You are a document retrieval expert. Given a question and
a hierarchical tree structure of a document, identify all
nodes likely to contain the answer. Each node has a node_id, title, and summary.
Follow cross-references if a section mentions another. Question: {query} Document tree structure:
{json.dumps(tree_without_text, indent=2)} Reply in this JSON format only:
{{
"thinking": "<reasoning about which nodes are relevant>",
"node_list": ["node_id_1", "node_id_2"]
}}
""" response = await openai_client.chat.completions.create(
model="gpt-4.1",
messages=[{"role": "user", "content": search_prompt}],
temperature=0,
response_format={"type": "json_object"},
) result = json.loads(response.choices[0].message.content)
print(f"LLM reasoning: {result['thinking']}")
return result["node_list"]
Отримання контенту та генерація відповіді
На етапі отримання контенту та його генерації необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних. Наводьте ті уривки, які фактично лежать в основі відповіді. Без посилань оператори не зможуть відрізнити галюцинацію від проблем із індексуванням.
def collect_node_content(tree: dict, node_ids: list) -> str:
"""Pull raw text from the nodes the LLM selected."""
all_nodes = utils.flatten_tree(tree)
context_parts = []
for node in all_nodes:
if node["node_id"] in node_ids:
title = node.get("title", "Untitled")
pages = f"pages {node.get('start_index', '?')}-{node.get('end_index', '?')}"
text = node.get("text", "")
context_parts.append(
f"[{title} | {pages}]\n{text}"
)
return "\n\n---\n\n".join(context_parts)
async def answer_query(tree: dict, query: str) -> dict:
"""Full vectorless RAG pipeline: tree search + answer generation.""" # Step 1: LLM picks the nodes
node_ids = await find_relevant_nodes(tree, query) # Step 2: Fetch content from those nodes
context = collect_node_content(tree, node_ids) # Step 3: Generate answer with citations
answer_prompt = f"""
Answer the question using only the provided context.
Cite specific pages and sections in your answer. Context:
{context} Question: {query}
""" response = await openai_client.chat.completions.create(
model="gpt-4.1",
messages=[{"role": "user", "content": answer_prompt}],
temperature=0,
) return {
"answer": response.choices[0].message.content,
"retrieved_nodes": node_ids,
"context_length": len(context),
}
# Run it
query = "What was the total value of deferred assets in 2023?"
result = asyncio.run(answer_query(tree, query))
print(result["answer"])
print(f"Nodes used: {result['retrieved_nodes']}")
Бонус: інтеграція MCP
Для етапу інтеграції MCP як бонусу необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення. Наводьте конкретні уривки, які лежать в основі відповіді. Без посилань оператори не зможуть відрізнити галюцинації від проблем з індексуванням. Для етапу інтеграції MCP як бонусу необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Зберігайте конфігурацію окремо від коду програми. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь код.
{
"mcpServers": {
"pageindex": {
"type": "http",
"url": "https://api.pageindex.ai/mcp",
"headers": {
"Authorization": "Bearer your_api_key"
}
}
}
}
{
"mcpServers": {
"pageindex": {
"command": "npx",
"args": ["-y", "@pageindex/mcp"]
}
}
}
Цифри бенчмарку (у контексті)
Під час роботи над етапом «Цифри бенчмарку у контексті» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допоможе зберегти чесність подальших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Перед налаштуванням запитів вимірюйте рівень відтворення інформації на фіксованому наборі запитань. Зміна запитів рідко допомагає покращити якість пошуку.
Де PageIndex не справляється (і це дійсно так)
Під час роботи над етапом «Де не вистачає PageIndex» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Такий перелік допомагає зберігати чесність під час подальших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Перед налаштуванням запитів вимірюйте рівень точності відповідей на фіксованому наборі запитань. Часта зміна формулювань запитів рідко допомагає покращити якість отримання інформації.
То коли ж насправді варто це використовувати?
Під час роботи над етапом «So When Should You» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Придумайте назви для результатів роботи, визначте критерії успіху та не допускайте беззвучного часткового виконання завдань. Перед налаштуванням запитів вимірюйте рівень точності на фіксованому наборі запитань. Часта зміна формулювань запитів рідко виправляє проблеми з низькою ефективністю пошуку. Під час роботи над етапом «So When Should You» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Зберігайте конфігурацію окремо від коду програми. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевіряти, не читаючи весь код.
Що сталось з моменту запуску (останні досягнення)
Етап «Що сталося» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Зафіксуйте один ідеальний варіант виконання, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Розділіть політику часткової обробки даних від політики їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.
pip install openai-agents
python3 examples/agentic_vectorless_rag_demo.py
Більша картина
Модель «The Bigger Picture» найкраще функціонує, якщо її розглядати як вимірювану поверхню. Збережіть один ідеальний зразок виконання, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Розділяйте політику часткового оброблення даних та політику їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу при зміні показників якості.
Початок роботи
Етап «Початок роботи» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Розділіть політику часткового оброблення даних від політики їх отримання. Зміна однієї з них не повинна змушувати переписувати іншу, коли змінюються показники якості. Етап «Початок роботи» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Зберігайте конфігурацію окремо від коду програми. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код.
Чек-лист для експлуатації
Під час роботи над етапом перевірки операційного процесу спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді.
Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ.
Виміряйте рівень точності відповідей на фіксований набір запитань перед налаштуванням формулювань запитів. Зміна формулювань рідко вирішує проблеми слабкої системи пошуку інформації.
Збережіть версії залежностей та записати хеш-значення зображень, які використовувалися під час демонстрації. Відтворюваність результатів краща за індивідуальні знання спеціалістів.
Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевіряти, не читаючи весь кодовий граф.
Вимірюйте рівень відтворення інформації на фіксованому наборі запитань перед налаштуванням підказок. Часта зміна підказок рідко вирішує проблеми слабкого пошуку даних.
Перед тим, як підвищувати рівень функціональності системи, заморозьте поточні версії, збережіть ідеальний запис для критичного шляху виконання та переконайтеся у наявності кроків для відкату. У спільних середовищах необхідні обмеження на частоту використання, перевірки прав доступу та чіткий власник для зміни секретних даних. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.
Примітка до d194e0549478: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на сеанс та зберігайте записи поруч із елементами для оцінки, щоб подальша заміна моделей залишалася порівнянною.
Під час роботи над етапом 0 записки про зміцнення спочатку складіть опис контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну послідовність дій.
Деталь зміцнення 0/751: виміряйте час виконання, клас помилки та кількість витрачених токенів для цієї записки, а потім вирішіть, чи залишити зміну, ґрунтуючись на фіксованому наборі критеріїв, а не на індивідуальних спостереженнях.
Етап 1 записки про зміцнення найкраще працює, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний зразок виконання, один випадок невдачі та записку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним витратам під час переходу з демо-середовища до спільних середовищ.
Деталі посилення безпеки 1/751: виміряйте час обробки стіни, клас помилки та витрати токенів для цього запису, а потім вирішіть, чи залишити зміни, ґрунтуючись на фіксованому наборі запитань, а не на окремих випадках.