@intlayer/docs 5.8.1-canary.0 → 6.0.0-canary.0

package/blog/pt/rag_powered_documentation_assistant.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)
+description: Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)
+keywords:
+  - RAG
+  - Documentação
+  - Assistente
+  - Fragmentação
+  - Embeddings
+  - Busca
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# Construindo um Assistente de Documentação com RAG (Fragmentação, Embeddings e Busca)
+
+## O que você recebe
+
+Eu construí um assistente de documentação com RAG e o empacotei em um boilerplate que você pode usar imediatamente.
+
+- Vem com uma aplicação pronta para uso (Next.js + OpenAI API)
+- Inclui um pipeline RAG funcional (fragmentação, embeddings, similaridade cosseno)
+- Fornece uma interface completa de chatbot construída em React
+- Todos os componentes da interface são totalmente editáveis com Tailwind CSS
+- Registra todas as consultas dos usuários para ajudar a identificar documentação faltante, pontos problemáticos dos usuários e oportunidades de produto
+
+👉 [Demo ao vivo](https://intlayer.org/doc/why) 👉 [Boilerplate do código](https://github.com/aymericzip/smart_doc_RAG)
+
+## Introdução
+
+Se você já se perdeu na documentação, rolando infinitamente em busca de uma resposta, sabe o quão frustrante isso pode ser. Documentações são úteis, mas são estáticas e a busca nelas muitas vezes parece desajeitada.
+
+É aí que entra o **RAG (Geração Aumentada por Recuperação)**. Em vez de forçar os usuários a vasculhar o texto, podemos combinar **recuperação** (encontrar as partes certas da documentação) com **geração** (permitir que um LLM explique de forma natural).
+
+Neste post, vou mostrar como construí um chatbot de documentação alimentado por RAG e como ele não apenas ajuda os usuários a encontrar respostas mais rapidamente, mas também oferece às equipes de produto uma nova forma de entender os pontos problemáticos dos usuários.
+
+## Por que usar RAG para documentação?
+
+RAG tornou-se uma abordagem popular por um motivo: é uma das maneiras mais práticas de tornar os grandes modelos de linguagem realmente úteis.
+
+Para documentação, os benefícios são claros:
+
+- Respostas instantâneas: os usuários perguntam em linguagem natural e recebem respostas relevantes.
+- Melhor contexto: o modelo vê apenas as seções mais relevantes da documentação, reduzindo alucinações.
+- Busca que parece humana: mais como Algolia + FAQ + chatbot, tudo em um.
+- Ciclo de feedback: ao armazenar consultas, você descobre com o que os usuários realmente têm dificuldades.
+
+Esse último ponto é crucial. Um sistema RAG não apenas responde perguntas, ele mostra o que as pessoas estão perguntando. Isso significa:
+
+- Você descobre informações faltantes na sua documentação.
+- Você vê surgirem pedidos de funcionalidades.
+- Você identifica padrões que podem até orientar a estratégia do produto.
+
+Portanto, RAG não é apenas uma ferramenta de suporte. É também um **motor de descoberta de produto**.
+
+## Como funciona o pipeline RAG
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+Em um nível geral, aqui está a receita que usei:
+
+1.  **Dividir a documentação em partes** Grandes arquivos Markdown são divididos em partes. Dividir permite fornecer como contexto apenas as partes relevantes da documentação.
+2.  **Gerar embeddings** Cada parte é transformada em um vetor usando a API de embedding da OpenAI (text-embedding-3-large) ou um banco de dados vetorial (Chroma, Qdrant, Pinecone).
+3.  **Indexação e armazenamento** Os embeddings são armazenados em um arquivo JSON simples (para minha demonstração), mas em produção, provavelmente você usaria um banco de dados vetorial.
+4.  **Recuperação (R em RAG)** A consulta do usuário é transformada em embedding, a similaridade cosseno é calculada, e os chunks mais relevantes são recuperados.
+5.  **Aumento + Geração (AG em RAG)** Esses chunks são injetados no prompt para o ChatGPT, para que o modelo responda com o contexto real da documentação.
+6.  **Registro de consultas para feedback** Cada consulta do usuário é armazenada. Isso é ouro para entender pontos problemáticos, documentação faltante ou novas oportunidades.
+
+## Passo 1: Lendo a Documentação
+
+O primeiro passo foi simples: eu precisava de uma forma de escanear uma pasta docs/ para todos os arquivos .md. Usando Node.js e glob, eu busquei o conteúdo de cada arquivo Markdown para a memória.
+
+Isso mantém o pipeline flexível: em vez de Markdown, você poderia buscar documentos de um banco de dados, um CMS ou até mesmo uma API.
+
+## Passo 2: Dividindo a Documentação em Partes
+
+Por que dividir em partes? Porque os modelos de linguagem têm **limites de contexto**. Alimentá-los com um livro inteiro de documentação não funciona.
+
+Então, a ideia é quebrar o texto em partes gerenciáveis (por exemplo, 500 tokens cada) com sobreposição (por exemplo, 100 tokens). A sobreposição garante continuidade para que você não perca o significado nas fronteiras das partes.
+
+**Exemplo:**
+
+- Parte 1 → “…a velha biblioteca que muitos haviam esquecido. Suas prateleiras imponentes estavam cheias de livros…”
+- Parte 2 → “…as prateleiras estavam cheias de livros de todos os gêneros imagináveis, cada um sussurrando histórias…”
+
+A sobreposição garante que ambas as partes contenham contexto compartilhado, para que a recuperação permaneça coerente.
+
+Esse equilíbrio (tamanho do chunk vs sobreposição) é fundamental para a eficiência do RAG:
+
+- Muito pequeno → você obtém ruído.
+- Muito grande → você estoura o tamanho do contexto.
+
+## Passo 3: Gerando Embeddings
+
+Uma vez que os documentos são divididos em chunks, geramos **embeddings** — vetores de alta dimensão que representam cada chunk.
+
+Usei o modelo text-embedding-3-large da OpenAI, mas você pode usar qualquer modelo moderno de embedding.
+
+**Exemplo de embedding:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 elementos
+];
+```
+
+Cada vetor é uma impressão digital matemática do texto, permitindo a busca por similaridade.
+
+## Passo 4: Indexando e Armazenando Embeddings
+
+Para evitar regenerar embeddings várias vezes, eu os armazenei em embeddings.json.
+
+Em produção, você provavelmente vai querer um banco de dados vetorial como:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus, etc.
+
+Bancos de dados vetoriais lidam com indexação, escalabilidade e busca rápida. Mas para meu protótipo, um JSON local funcionou bem.
+
+## Passo 5: Recuperação com Similaridade Cosseno
+
+Quando um usuário faz uma pergunta:
+
+1. Gere um embedding para a consulta.
+2. Compare-o com todos os embeddings dos documentos usando **similaridade cosseno**.
+3. Mantenha apenas os N chunks mais similares.
+
+A similaridade cosseno mede o ângulo entre dois vetores. Uma correspondência perfeita tem pontuação **1.0**.
+
+Dessa forma, o sistema encontra as passagens do documento mais próximas da consulta.
+
+## Passo 6: Aumento + Geração
+
+Agora vem a mágica. Pegamos os chunks principais e os injetamos no **prompt do sistema** para o ChatGPT.
+
+Isso significa que o modelo responde como se esses trechos fizessem parte da conversa.
+
+O resultado: respostas precisas e **baseadas na documentação**.
+
+## Passo 7: Registro das Consultas dos Usuários
+
+Este é o superpoder oculto.
+
+Cada pergunta feita é armazenada. Com o tempo, você constrói um conjunto de dados de:
+
+- Perguntas mais frequentes (ótimo para FAQs)
+- Perguntas sem resposta (documentação ausente ou pouco clara)
+- Solicitações de funcionalidades disfarçadas de perguntas (“Integra com X?”)
+- Casos de uso emergentes que você não havia planejado
+
+Isso transforma seu assistente RAG em uma **ferramenta contínua de pesquisa com usuários**.
+
+## Quanto Custa?
+
+Uma objeção comum ao RAG é o custo. Na prática, é surpreendentemente barato:
+
+- Gerar embeddings para cerca de 200 documentos leva cerca de **5 minutos** e custa **1–2 euros**.
+- O recurso de busca na documentação é 100% gratuito.
+- Para consultas, usamos o gpt-4o-latest sem o modo “thinking”. No Intlayer, vemos cerca de **300 consultas de chat por mês**, e a fatura da API OpenAI raramente ultrapassa **10 dólares**.
+
+Além disso, você pode incluir o custo de hospedagem.
+
+## Detalhes da Implementação
+
+Stack:
+
+- Monorepo: workspace pnpm
+- Pacote de documentação: Node.js / TypeScript / API OpenAI
+- Frontend: Next.js / React / Tailwind CSS
+- Backend: rota API Node.js / API OpenAI
+
+O pacote `@smart-doc/docs` é um pacote TypeScript que lida com o processamento da documentação. Quando um arquivo markdown é adicionado ou modificado, o pacote inclui um script `build` que reconstrói a lista de documentação em cada idioma, gera embeddings e os armazena em um arquivo `embeddings.json`.
+
+Para o frontend, usamos uma aplicação Next.js que fornece:
+
+- Renderização de Markdown para HTML
+- Uma barra de pesquisa para encontrar documentação relevante
+- Uma interface de chatbot para fazer perguntas sobre a documentação
+
+Para realizar uma busca na documentação, a aplicação Next.js inclui uma rota de API que chama uma função do pacote `@smart-doc/docs` para recuperar fragmentos de documentação que correspondem à consulta. Usando esses fragmentos, podemos retornar uma lista de páginas de documentação relevantes para a busca do usuário.
+
+Para a funcionalidade do chatbot, seguimos o mesmo processo de busca, mas além disso, injetamos os fragmentos de documentação recuperados no prompt enviado ao ChatGPT.
+
+Aqui está um exemplo de um prompt enviado ao ChatGPT:
+
+Prompt do sistema:
+
+```txt
+Você é um assistente prestativo que pode responder perguntas sobre a documentação do Intlayer.
+
+Fragmentos relacionados:
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/pt/getting-started"
+---
+
+# Como começar
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/pt/another-doc"
+---
+
+# Outro documento
+
+...
+```
+
+Consulta do usuário :
+
+```txt
+Como começar?
+```
+
+Usamos SSE para transmitir a resposta da rota da API.
+
+Como mencionado, usamos gpt-4-turbo sem o modo "thinking". As respostas são relevantes e a latência é baixa.
+Experimentamos com o gpt-5, mas a latência era muito alta (às vezes até 15 segundos para uma resposta). Mas revisaremos isso no futuro.
+
+👉 [Experimente a demonstração aqui](https://intlayer.org/doc/why) 👉 [Confira o modelo de código no GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+## Indo Além
+
+Este projeto é uma implementação mínima. Mas você pode estendê-lo de várias maneiras:
+
+- Servidor MCP → a função de pesquisa de documentação para um servidor MCP para conectar a documentação a qualquer assistente de IA
+
+- Bancos de Dados Vetoriais → escalar para milhões de pedaços de documentação
+- LangChain / LlamaIndex → frameworks prontos para pipelines RAG
+- Painéis de análise → visualizar consultas dos usuários e pontos problemáticos
+- Recuperação multi-fonte → buscar não apenas documentos, mas entradas de banco de dados, posts de blog, tickets, etc.
+- Melhoria no prompting → reclassificação, filtragem e busca híbrida (palavra-chave + semântica)
+
+## Limitações que Encontramos
+
+- A segmentação e sobreposição são empíricas. O equilíbrio correto (tamanho do pedaço, porcentagem de sobreposição, número de pedaços recuperados) requer iteração e testes.
+- Embeddings não são regenerados automaticamente quando os documentos mudam. Nosso sistema redefine os embeddings para um arquivo somente se o número de pedaços for diferente do que está armazenado.
+- Neste protótipo, os embeddings são armazenados em JSON. Isso funciona para demonstrações, mas polui o Git. Em produção, um banco de dados ou um armazenamento vetorial dedicado é melhor.
+
+## Por Que Isso Importa Além da Documentação
+
+A parte interessante não é apenas o chatbot. É o **ciclo de feedback**.
+
+Com RAG, você não apenas responde:
+
+- Você aprende o que confunde os usuários.
+- Você descobre quais recursos eles esperam.
+- Você adapta sua estratégia de produto com base em consultas reais.
+
+**Exemplo:**
+
+Imagine lançar um novo recurso e ver instantaneamente:
+
+- 50% das perguntas são sobre o mesmo passo de configuração pouco claro
+- Usuários pedem repetidamente por uma integração que você ainda não suporta
+- Pessoas buscam termos que revelam um novo caso de uso
+
+Isso é **inteligência de produto** diretamente dos seus usuários.
+
+## Conclusão
+
+RAG é uma das formas mais simples e poderosas de tornar os LLMs práticos. Ao combinar **recuperação + geração**, você pode transformar documentos estáticos em um **assistente inteligente** e, ao mesmo tempo, obter um fluxo contínuo de insights sobre o produto.
+
+Para mim, este projeto mostrou que RAG não é apenas um truque técnico. É uma forma de transformar a documentação em:
+
+- um sistema de suporte interativo
+- um canal de feedback
+- uma ferramenta de estratégia de produto
+
+👉 [Experimente a demonstração aqui](https://intlayer.org/doc/why) 👉 [Confira o modelo de código no GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+E se você também estiver experimentando com RAG, adoraria saber como está usando.

package/blog/ru/rag_powered_documentation_assistant.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-09-10
+updatedAt: 2025-09-10
+title: Создание помощника по документации на базе RAG (разбиение на части, эмбеддинги и поиск)
+description: Создание помощника по документации на базе RAG (разбиение на части, эмбеддинги и поиск)
+keywords:
+  - RAG
+  - Документация
+  - Помощник
+  - Разбиение на части
+  - Эмбеддинги
+  - Поиск
+slugs:
+  - blog
+  - rag-powered-documentation-assistant
+---
+
+# Создание помощника по документации на базе RAG (разбиение на части, эмбеддинги и поиск)
+
+## Что вы получите
+
+Я создал помощника по документации на базе RAG и упаковал его в шаблон, который вы можете использовать сразу.
+
+- В комплекте готовое к использованию приложение (Next.js + OpenAI API)
+- Включает рабочий RAG-пайплайн (разбиение на части, эмбеддинги, косинусное сходство)
+- Предоставляет полный интерфейс чат-бота, построенный на React
+- Все компоненты пользовательского интерфейса полностью редактируются с помощью Tailwind CSS
+- Логирует каждый запрос пользователя, чтобы помочь выявить отсутствующую документацию, болевые точки пользователей и возможности для продукта
+
+👉 [Демо в реальном времени](https://intlayer.org/doc/why) 👉 [Шаблон кода](https://github.com/aymericzip/smart_doc_RAG)
+
+## Введение
+
+Если вы когда-либо терялись в документации, бесконечно прокручивая в поисках одного ответа, вы знаете, как это может быть мучительно. Документация полезна, но она статична, и поиск по ней часто кажется неудобным.
+
+Вот тут и приходит на помощь **RAG (Retrieval-Augmented Generation)**. Вместо того чтобы заставлять пользователей рыться в тексте, мы можем объединить **извлечение** (нахождение нужных частей документа) с **генерацией** (позволяя большой языковой модели объяснять это естественным языком).
+
+В этом посте я расскажу, как я создал чатбот для документации на базе RAG и как он не только помогает пользователям быстрее находить ответы, но и предоставляет командам продукта новый способ понимания болевых точек пользователей.
+
+## Почему стоит использовать RAG для документации?
+
+RAG стал популярным подходом не случайно: это один из самых практичных способов сделать большие языковые модели действительно полезными.
+
+Для документации преимущества очевидны:
+
+- Мгновенные ответы: пользователи задают вопросы на естественном языке и получают релевантные ответы.
+- Лучший контекст: модель видит только самые релевантные разделы документации, что снижает количество ошибок (галлюцинаций).
+- Поиск, который ощущается как человеческий: что-то вроде сочетания Algolia + FAQ + чатбота в одном.
+- Обратная связь: сохраняя запросы, вы выявляете, с чем пользователи действительно испытывают трудности.
+
+Этот последний пункт очень важен. Система RAG не просто отвечает на вопросы, она показывает, что именно спрашивают люди. Это значит:
+
+- Вы обнаруживаете недостающую информацию в вашей документации.
+- Вы видите появляющиеся запросы на новые функции.
+- Вы замечаете закономерности, которые могут даже направлять стратегию продукта.
+
+Таким образом, RAG — это не просто инструмент поддержки. Это также **движок для обнаружения продукта**.
+
+## Как работает конвейер RAG
+
+![RAG Pipeline](https://github.com/aymericzip/intlayer/blob/main/docs/assets/rag_flow.svg)
+
+В общих чертах, вот рецепт, который я использовал:
+
+1.  **Разбиение документации на части** Большие Markdown-файлы разбиваются на части. Разбиение позволяет предоставлять в качестве контекста только релевантные части документации.
+2.  **Генерация эмбеддингов** Каждая часть преобразуется в вектор с помощью API эмбеддингов OpenAI (text-embedding-3-large) или векторной базы данных (Chroma, Qdrant, Pinecone).
+3.  **Индексация и хранение** Встраивания сохраняются в простом JSON-файле (для моего демо), но в продакшене вы, скорее всего, будете использовать векторную базу данных.
+4.  **Извлечение (R в RAG)** Запрос пользователя преобразуется в вектор, вычисляется косинусное сходство, и извлекаются наиболее подходящие фрагменты.
+5.  **Дополнение и генерация (AG в RAG)** Эти фрагменты вставляются в подсказку для ChatGPT, чтобы модель отвечала с учетом реального контекста документации.
+6.  **Логирование запросов для обратной связи** Каждый пользовательский запрос сохраняется. Это бесценно для понимания болевых точек, отсутствующей документации или новых возможностей.
+
+## Шаг 1: Чтение документации
+
+Первый шаг был простым: мне нужно было просканировать папку docs/ на наличие всех файлов с расширением .md. Используя Node.js и glob, я загрузил содержимое каждого Markdown-файла в память.
+
+Это сохраняет гибкость конвейера: вместо Markdown вы можете получать документы из базы данных, CMS или даже API.
+
+## Шаг 2: Разбиение документации на части
+
+Зачем разбивать? Потому что у языковых моделей есть **ограничения по контексту**. Передавать им целую книгу документации не получится.
+
+Идея в том, чтобы разбить текст на управляемые части (например, по 500 токенов каждая) с перекрытием (например, 100 токенов). Перекрытие обеспечивает непрерывность, чтобы вы не теряли смысл на границах частей.
+
+**Пример:**
+
+- Часть 1 → «…старая библиотека, которую многие забыли. Ее высокие полки были заполнены книгами…»
+- Часть 2 → «…полки были заполнены книгами из всех мыслимых жанров, каждая шептала свои истории…»
+
+Перекрытие гарантирует, что обе части содержат общий контекст, поэтому извлечение остается последовательным.
+
+Этот компромисс (размер чанка против перекрытия) является ключевым для эффективности RAG:
+
+- Слишком маленький → появляется шум.
+- Слишком большой → увеличивается размер контекста.
+
+## Шаг 3: Генерация эмбеддингов
+
+После разбиения документов на чанки мы генерируем **эмбеддинги** — векторы высокой размерности, представляющие каждый чанк.
+
+Я использовал модель OpenAI text-embedding-3-large, но вы можете использовать любую современную модель эмбеддингов.
+
+**Пример эмбеддинга:**
+
+```js
+[
+  -0.0002630692, -0.029749284, 0.010225477, -0.009224428, -0.0065269712,
+  -0.002665544, 0.003214777, 0.04235309, -0.033162255, -0.00080789323,
+  //...+1533 элементов
+];
+```
+
+Каждый вектор — это математический отпечаток текста, позволяющий выполнять поиск по сходству.
+
+## Шаг 4: Индексация и хранение эмбеддингов
+
+Чтобы избежать многократной генерации эмбеддингов, я сохранил их в файле embeddings.json.
+
+В продакшене вам, скорее всего, понадобится векторная база данных, такая как:
+
+- Chroma
+- Qdrant
+- Pinecone
+- FAISS, Weaviate, Milvus и др.
+
+Векторные базы данных обеспечивают индексацию, масштабируемость и быстрый поиск. Но для моего прототипа локальный JSON отлично подошёл.
+
+## Шаг 5: Поиск с помощью косинусного сходства
+
+Когда пользователь задаёт вопрос:
+
+1.  Генерируется эмбеддинг для запроса.
+2.  Сравнивается с эмбеддингами всех документов с использованием **косинусного сходства**.
+3.  Оставляются только топ N наиболее похожих чанков.
+
+Косинусное сходство измеряет угол между двумя векторами. Идеальное совпадение оценивается в **1.0**.
+
+Таким образом система находит наиболее близкие к запросу фрагменты документа.
+
+## Шаг 6: Расширение + Генерация
+
+Теперь начинается магия. Мы берём топ чанков и вставляем их в **системный промпт** для ChatGPT.
+
+Это означает, что модель отвечает так, как будто эти фрагменты были частью разговора.
+
+Результат: точные, **основанные на документации ответы**.
+
+## Шаг 7: Логирование запросов пользователей
+
+Это скрытая суперсила.
+
+Каждый заданный вопрос сохраняется. Со временем вы создаёте набор данных из:
+
+- Наиболее частых вопросов (отлично подходит для FAQ)
+- Невыясненных вопросов (документация отсутствует или неясна)
+- Запросов на функции, замаскированных под вопросы («Интегрируется ли с X?»)
+- Новых сценариев использования, которые вы не планировали
+
+Это превращает вашего RAG-ассистента в **инструмент непрерывного исследования пользователей**.
+
+## Сколько это стоит?
+
+Одно из распространённых возражений против RAG — стоимость. На практике это удивительно дешево:
+
+- Генерация эмбеддингов для ~200 документов занимает около **5 минут** и стоит **1–2 евро**.
+- Функция поиска по документации абсолютно бесплатна.
+- Для запросов мы используем gpt-4o-latest без режима «размышления». В Intlayer мы наблюдаем около **300 запросов в чатах в месяц**, и счет за OpenAI API редко превышает **10 долларов**.
+
+Кроме того, вы можете включить стоимость хостинга.
+
+## Детали реализации
+
+Стек:
+
+- Монорепозиторий: pnpm workspace
+- Пакет документации: Node.js / TypeScript / OpenAI API
+- Фронтенд: Next.js / React / Tailwind CSS
+- Бэкенд: Node.js API route / OpenAI API
+
+Пакет `@smart-doc/docs` — это пакет на TypeScript, который обрабатывает документацию. Когда добавляется или изменяется markdown-файл, пакет включает скрипт `build`, который перестраивает список документации на каждом языке, генерирует embeddings и сохраняет их в файл `embeddings.json`.
+
+Для фронтенда мы используем приложение Next.js, которое предоставляет:
+
+- Преобразование Markdown в HTML
+- Поисковая строка для поиска релевантной документации
+- Интерфейс чат-бота для задавания вопросов по документации
+
+Для выполнения поиска по документации приложение Next.js включает API-маршрут, который вызывает функцию из пакета `@smart-doc/docs` для получения фрагментов документации, соответствующих запросу. Используя эти фрагменты, мы можем вернуть список страниц документации, релевантных поиску пользователя.
+
+Для функционала чат-бота мы используем тот же процесс поиска, но дополнительно внедряем полученные фрагменты документации в подсказку, отправляемую в ChatGPT.
+
+Вот пример подсказки, отправляемой в ChatGPT:
+
+Системная подсказка:
+
+```txt
+Вы — полезный помощник, который может отвечать на вопросы по документации Intlayer.
+
+Связанные фрагменты:
+
+-----
+docName: "getting-started"
+docChunk: "1/3"
+docUrl: "https://example.com/docs/ru/getting-started"
+---
+
+# Как начать
+
+...
+
+-----
+docName: "another-doc"
+docChunk: "1/5"
+docUrl: "https://example.com/docs/ru/another-doc"
+---
+
+# Другой документ
+
+...
+```
+
+Запрос пользователя :
+
+```txt
+Как начать?
+```
+
+Мы используем SSE для потоковой передачи ответа с API маршрута.
+
+Как упоминалось, мы используем gpt-4-turbo без режима "размышления". Ответы релевантны, а задержка низкая.
+Мы экспериментировали с gpt-5, но задержка была слишком высокой (иногда до 15 секунд на ответ). Однако мы вернемся к этому в будущем.
+
+👉 [Попробуйте демо здесь](https://intlayer.org/doc/why) 👉 [Посмотрите шаблон кода на GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+## Дальнейшие шаги
+
+Этот проект является минимальной реализацией. Но вы можете расширить его во многих направлениях:
+
+- MCP сервер → функция поиска по документации на MCP сервер для подключения документации к любому AI-ассистенту
+
+- Векторные базы данных → масштабирование до миллионов фрагментов документации
+- LangChain / LlamaIndex → готовые фреймворки для RAG-пайплайнов
+- Аналитические панели → визуализация запросов пользователей и проблемных точек
+- Многоисточниковый поиск → извлечение не только документов, но и записей из баз данных, блогов, тикетов и т.д.
+- Улучшенный prompting → повторная ранжировка, фильтрация и гибридный поиск (ключевые слова + семантика)
+
+## Ограничения, с которыми мы столкнулись
+
+- Разбиение на фрагменты и перекрытие эмпиричны. Правильный баланс (размер фрагмента, процент перекрытия, количество извлекаемых фрагментов) требует итераций и тестирования.
+- Встраивания (embeddings) не регенерируются автоматически при изменении документации. Наша система сбрасывает встраивания для файла только если количество фрагментов отличается от сохранённого.
+- В этом прототипе эмбеддинги хранятся в формате JSON. Это подходит для демонстраций, но засоряет Git. В продакшене лучше использовать базу данных или специализированное хранилище векторов.
+
+## Почему это важно не только для документации
+
+Интересная часть — это не просто чат-бот. Это **обратная связь**.
+
+С RAG вы не просто отвечаете:
+
+- Вы узнаёте, что сбивает пользователей с толку.
+- Вы обнаруживаете, какие функции они ожидают.
+- Вы адаптируете стратегию продукта на основе реальных запросов.
+
+**Пример:**
+
+Представьте, что вы запускаете новую функцию и сразу видите:
+
+- 50% вопросов касаются одного и того же непонятного шага настройки
+- Пользователи постоянно просят интеграцию, которую вы ещё не поддерживаете
+- Люди ищут термины, которые выявляют новый сценарий использования
+
+Это **продуктовая аналитика** прямо от ваших пользователей.
+
+## Заключение
+
+RAG — один из самых простых и мощных способов сделать LLM практичными. Объединив **извлечение + генерацию**, вы можете превратить статичную документацию в **умного помощника** и одновременно получить непрерывный поток инсайтов о продукте.
+
+Для меня этот проект показал, что RAG — это не просто технический трюк. Это способ преобразовать документацию в:
+
+- интерактивную систему поддержки
+- канал обратной связи
+- инструмент для продуктовой стратегии
+
+👉 [Попробуйте демо здесь](https://intlayer.org/doc/why) 👉 [Посмотрите шаблон кода на GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+Если вы тоже экспериментируете с RAG, мне было бы интересно узнать, как вы его используете.

package/blog/tr/index.md

@@ -0,0 +1,69 @@
+---
+createdAt: 2025-09-07
+updatedAt: 2025-09-07
+title: Blog
+description: Intlayer, uluslararasılaştırma ve diğer konularla ilgili tüm konuları keşfedin
+keywords:
+  - Intlayer
+  - Internationalization
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - search
+---
+
+# JavaScript'te Uluslararasılaştırmayı Kucaklamak: Küresel Erişimi ve SEO'yu Geliştirme
+
+JavaScript uygulamaları için **uluslararasılaştırma (i18n)** ile ilgili her şeye adanmış blogumuza hoş geldiniz! Burada, geliştiricilerin dijital ürünlerini dünya çapında genişletmelerine yardımcı olacak en iyi uygulamaları, stratejileri ve araçları keşfediyoruz.
+
+---
+
+## Neden Uluslararasılaştırma (i18n) Önemli
+
+Günümüzün birbirine bağlı dünyasında, kullanıcılar sorunsuz, yerelleştirilmiş deneyimler bekliyor. **Uluslararasılaştırma (i18n)**, web uygulamanızın farklı dillere ve kültürel nüanslara uyum sağlamasını sağlar. Başlangıçtan itibaren i18n uygulamalarını dahil ederek, aşağıdaki gibi birçok fayda elde edersiniz:
+
+1. **Geliştirilmiş Kullanıcı Deneyimi:** Kullanıcılar, ana dillerindeki içerikle etkileşim kurmak daha rahat hisseder.
+2. **Daha Geniş Pazar Erişimi:** Birden fazla dil sunmak, yeni bölgelere ulaşmanıza ve kullanıcı tabanınızı büyütmenize yardımcı olur.
+3. **İyileştirilmiş Erişilebilirlik:** İyi yapılandırılmış i18n, genellikle erişilebilirlik standartlarıyla uyumlu olur ve uygulamanızı daha kapsayıcı hale getirir.
+4. **Daha İyi SEO Performansı:** Yerelleştirilmiş içerik, bölgeye özgü arama sonuçlarında görünürlüğünüzü artırabilir.
+
+---
+
+## Açık Kaynak Uluslararasılaştırma Çözümleri
+
+Uluslararasılaştırılmış bir uygulama oluşturmak karmaşık olmak zorunda değil. Açık kaynak topluluğu, yerelleştirmeyi daha kolay hale getiren birçok güçlü, iyi desteklenen araç ve kütüphane sağlar. React, Vue ve Angular gibi modern JavaScript çerçeveleriyle kolay entegrasyon sağlayan **react-intl**, **i18next** ve **FormatJS** gibi popüler çözümler, esnek API'ler sunar.
+
+### Açık Kaynak Çözümlerinin Ana Faydaları
+
+- **Esneklik:** Topluluk odaklı kütüphaneler hızla evrilir ve ihtiyaçlar ortaya çıktıkça güncellemeler ve yeni özellikler sunar.
+- **Maliyet Tasarrufu:** Lisans ücretleri yok, uygulamanızı test etmeyi veya ölçeklendirmeyi daha basit hale getirir.
+- **Topluluk Desteği:** Büyük topluluklar genellikle daha fazla öğretici, dokümantasyon ve hazır eklentiler anlamına gelir.
+
+---
+
+## Duyurular ve Gelecek
+
+Gelecekteki öğreticiler, en iyi uygulamalar ve JavaScript uygulamalarınızı küresel kitleler için optimize etme üzerine **vaka çalışmaları** hakkında heyecanlıyız. İşte bir ön izleme:
+
+- **Gelişmiş Yerelleştirme İpuçları:** Çoğullaştırma, tarih/saat biçimlendirme ve dinamik içerik ustalaşma.
+- **Performans Optimizasyonları:** Birden fazla yerel desteklenirken paket boyutlarını minimize etme.
+- **Topluluktan Vaka Çalışmaları:** Başarılı i18n uygulamalarının gerçek dünya örneklerini sergileme.
+
+Bu güncellemeler ve daha fazlası için bizi takip edin!
+
+---
+
+## Blogumuza Katkıda Bulunun!
+
+Topluluk odaklı bilgi paylaşımına inanıyoruz. Uluslararasılaştırma, **SEO** veya başka ilgili bir konu hakkında harika bir blog yazısı fikriniz varsa, sizden duymak isteriz. Önerilen blog yazınızı GitHub deposumuza ekleyerek bir Pull Request gönderebilirsiniz:
+
+[**Yazınızı buraya gönderin**](https://github.com/aymericzip/intlayer/blob/main/docs/blog)
+
+Katkılarınız bu platformu zenginleştirir ve dünya çapındaki geliştiricilere güç verir.
+
+---
+
+**Okuduğunuz için teşekkür ederiz ve i18n topluluğumuza hoş geldiniz!** JavaScript uygulamalarınızı uluslararası başarıya taşımak için daha fazla içgörü, ipucu ve en iyi uygulama için bizi takip edin.