Gonka Discussions
Gonka GitHub Discussions · Discussion #1345

Документация сети

Отдельная страница дискуссии с русским переводом и параллельным режимом RU / Original с точным сопоставлением предложений.

← Protocol Improvements · Все дискуссии
Как пользоваться: включите RU / Original и кликните по предложению — соответствующее предложение в другой колонке доскроллится и подсветится.
Discussion #1345

Документация сети

Оригинал: Network Documentation

heitor-lassarote avatar
heitor-lassaroteАвтор

Всем привет. Мы — команда Serokell (https://serokell.io/), и после прочтения дорожной карты сети сообщества Gonka (https://docs.google.com/document/d/1wPXTM40CnXyd8Hz_dvf7H1n6KQDqjw0RzppMx92xR8U/edit?pli=1&tab=t.0#heading=h.wt1svxjuy5ac), мы хотели обсудить трек 4, проект 3, озаглавленный «Сетевая документация», который имеет следующее описание по состоянию на 06.09.2026:

Структурированная система документации для хостов, разработчиков, внешних участников и команд экосистемы.

Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.

К этому проекту следует относиться как к постоянному процессу ведения документации, а не как к разовой работе по ее написанию. Он может поддерживать группу разработчиков документации или технических специалистов, ответственную за поддержание актуальности документации после обновлений протокола, инцидентов, повторяющихся вопросов поддержки и эксплуатационных изменений.

Метрики:

  • ПЕРВИЧНЫЙ: надежность и доверие сети.
  • ВТОРИЧНЫЙ: более низкая нагрузка на поддержку; более быстрая регистрация хоста.

Что это дает сети:

Gonka получает четкую, поддерживаемую и версионируемую базу знаний. Хозяева и внешние команды получают меньше двусмысленных инструкций и более безопасный путь при обновлении и операционных изменениях.

Мы хотели бы предложить команду для работы над структурированной документацией. В частности, мы хотели бы предложить следующие улучшения существующей документации:

  • Внедрите агента искусственного интеллекта для ответа на вопросы, связанные с документацией. Существует несколько вариантов владения/финансирования агента: Финансируется сообществом (пул сообщества): постоянный бюджет на хостинг и обслуживание. Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры». Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу. Варианты хостинга: Самостоятельное размещение на Gonka infra: требуется владение операционной системой. Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу. Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера. Выбор модели: начните с экономически эффективной модели: компромисс между качеством, задержкой и ценой. Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины. Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д. Защита от вредоносных и несвязанных запросов: на данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки. По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций. Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • Существует несколько вариантов владения/финансирования агента: Финансируется сообществом (пул сообщества): текущий бюджет на хостинг и обслуживание. Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры». Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Финансируется сообществом (пул сообщества): постоянный бюджет на хостинг и обслуживание.
  • Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры».
  • Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Варианты хостинга: Самостоятельное размещение на Gonka infra: требуется владение операционной системой. Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу. Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера.
  • Самостоятельное размещение на Gonka infra: требуется владение операционной системой.
  • Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера.
  • Выбор модели: начните с экономически эффективной модели: компромисс между качеством, задержкой и ценой. Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины. Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Начните с экономичной модели: компромисс между качеством, задержкой и ценой.
  • Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины.
  • Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок.
  • Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок.
  • Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов.
  • Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Защита от вредоносных и несвязанных запросов: на данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки. По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций. Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • На данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки.
  • По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций.
  • Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • Версионная документация. В данный момент может использоваться более одной сетевой версии. Переключатель, позволяющий выбрать чтение документации для конкретной версии, поможет аудитории, которая не находится в одной сети или версии программного обеспечения в одно и то же время. Похоже, что у Gonka есть поддерживаемая тестовая сеть, но доступность может контролироваться/основаться на запросах. Таким образом, версионные документы могут учитывать не только версию, но и сеть. Один из возможных планов — согласовать версию документации с тегами/ветвями выпуска GitHub. Документацию для версии следует получить на основе тега. Также может потребоваться управление версиями для конкретной сети. Сопровождающие и разработчики должны координировать усилия по поддержанию актуальности документации. Одним из вариантов помощи является использование агента в gonka-docs для отслеживания последних различий в репозитории gonka с основной веткой, в которой следует изменить gonka-docs. Однако этот вариант требует кредитов, и при больших различиях (обычно в gonka) результаты могут быть посредственными. Мы предлагаем провести эксперимент и проверить, как это будет происходить.
  • Похоже, что у Gonka есть поддерживаемая тестовая сеть, но доступность может контролироваться/основаться на запросах. Таким образом, версионные документы могут учитывать не только версию, но и сеть.
  • Один из возможных планов — согласовать версию документации с тегами/ветвями выпуска GitHub. Документацию для версии следует получить на основе тега. Также может потребоваться управление версиями для конкретной сети.
  • Сопровождающие и разработчики должны координировать усилия по поддержанию актуальности документации. Одним из вариантов помощи является использование агента в gonka-docs для отслеживания последних различий в репозитории gonka с основной веткой, в которой следует изменить gonka-docs. Однако этот вариант требует кредитов, и при больших различиях (обычно в gonka) результаты могут быть посредственными. Мы предлагаем провести эксперимент и проверить, как это будет происходить.
  • Автоматический перевод на другие языки. После улучшения агента искусственного интеллекта документация Gonka теперь написана на английском и китайском языках. Используя английскую версию в качестве источника истины, мы можем добавить третий вариант, позволяющий автоматически переводить на другие языки. Каждый переведенный документ будет ссылаться на исходный документ на английском языке. Тестирование будет проводиться модельным судьей с использованием репрезентативных языковых групп (русского, китайского и т. д.). Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее. Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Каждый переведенный документ будет ссылаться на исходный документ на английском языке.
  • Тестирование будет проводиться модельным судьей с использованием репрезентативных языковых групп (русского, китайского и т. д.). Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее. Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее.
  • Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Метрики и телеметрия для поиска документов и посещений страниц. Использование документации: Просмотров на страницу: отслеживайте основные точки входа и критические пути. Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался». Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики. Поисковая телеметрия: поисковые запросы (анонимные): обнаруживайте недостающие темы и запутанную терминологию. Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить. Запрос → результат клика: измеряйте релевантность поиска и качество навигации. Отслеживание качества: «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы. Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий. Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером. Поддержка: Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации. Хостинг: Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Использование документации: Просмотров на страницу: отслеживайте основные точки входа и критические пути. Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался». Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики.
  • Просмотров на страницу: отслеживайте основные точки входа и критические пути.
  • Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался».
  • Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики.
  • Поисковая телеметрия: поисковые запросы (анонимные): обнаруживайте недостающие темы и запутанную терминологию. Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить. Запрос → результат клика: измеряйте релевантность поиска и качество навигации.
  • Поисковые запросы (анонимные): найдите недостающие темы и запутанную терминологию.
  • Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить.
  • Запрос → результат клика: измеряйте релевантность поиска и качество навигации.
  • Отслеживание качества: «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы. Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий. Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером.
  • «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы.
  • Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий.
  • Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером.
  • Поддержка: Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации.
  • Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации.
  • Хостинг: Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Проведите аудит и разрешите предложенные проблемы/обсуждения/комментарии по связям с общественностью относительно документации в репозитории Gonka, представленные в разделе «Проблемы, связанные с документацией, запросы на запросы и обсуждения» ниже. Они будут использоваться в качестве исходных данных для улучшения документации.
  • Найдите и перенесите соответствующую документацию из репозитория кода в репозиторий документации.

График поддержки вышеуказанного плана может выглядеть следующим образом:

  • Создайте инфраструктуру и внедрите метрики и телеметрию для документации.
  • Внедрите функцию управления версиями документов и напишите для нее тесты.
  • (Пере)писать документацию на основе предложенного списка вопросов и обсуждений.
  • Найдите и перенесите соответствующую документацию из репозитория кода в репозиторий документации.
  • Разработайте и интегрируйте агента ИИ, используя репозиторий знаний gonka-ai/gonka-docs (https://github.com/gonka-ai/gonka-docs), и добавьте его в https://gonka.ai/docs/, добавив новую кнопку, например «Спросить агента».
  • Создайте набор оценок и проверьте качество ответов.
  • Используя ранее реализованный AI-агент, поддержите новый переключатель, помимо английского и китайского, например «Другое (автоперевод)».
  • Создавайте оценки переведенного контента.
  • Напишите план, четко описывающий, как передать эти новые функции сообществу Gonka.
  • Целевой моделью является постоянное техническое обслуживание. Если финансирование ограничено, первоначальный объем может включать единовременную начальную загрузку и план передачи.

Проблемы, связанные с документацией, PR и обсуждения

Соответствующие PR:

  • документы: добавьте переводы на китайский (zh) для ключевой документации № 1327 (https://github.com/gonka-ai/gonka/pull/1327) : docs: добавьте переводы на китайский (zh) для ключевой документации Не объединено, предложено в неправильном репозитории.
  • Не объединено, предложено в неправильном репозитории.

Соответствующие вопросы:

  • Как получить ключ API брокера для node4 (или документацию по процессу регистрации брокера)? #1331 (https://github.com/gonka-ai/gonka/issues/1331): Как получить ключ API брокера для node4 (или документацию по процессу регистрации брокера)? Открытая проблема с запросом документации.
  • Открытая проблема с запросом документации.
  • Поток самообслуживания (без брокера) задокументирован как рабочий, но возвращает 401 «модель требует ключ API» — я хочу потратить свой собственный GNK напрямую # 1319 (https://github.com/gonka-ai/gonka/issues/1319): Поток самообслуживания (без брокера) документирован как рабочий, но возвращает 401 «модель требует ключ API» — я хочу потратить свой собственный GNK напрямую Запрашивает изменения кода, но предполагает, что документы могут быть более ясными.
  • Запрашивает изменения кода, но предлагает, чтобы документация была более понятной.
  • Запустить перевод документации Gonka на Gonka gonka-docs#1149 (https://github.com/gonka-ai/gonka-docs/issues/1149): Запустить перевод документации Gonka на Gonka. Один из предлагаемых нами рабочих пунктов, касающихся автоматического перевода.
  • Один из предложенных нами пунктов работы касается автоматического перевода.
  • Вопрос: есть ли возможность использовать графические процессоры потребительского уровня с объемом памяти 16 ГБ в качестве облегченных хост-узлов? #1032 (https://github.com/gonka-ai/gonka/issues/1032): Вопрос: есть ли возможность использовать графические процессоры потребительского уровня с 16 ГБ памяти в качестве облегченных хост-узлов? Проблема была преобразована в беседу, доступную только соавторам, и на нее нет ответа.
  • Проблема была преобразована в беседу, доступную только соавторам, и на нее нет ответа.
  • Регистрация узла не обновляется после миграции (API зависает с использованием старой конфигурации цепочки) # 447 (https://github.com/gonka-ai/gonka/issues/447): Регистрация узла не обновляется после миграции (API зависает с использованием старой конфигурации цепочки). Проблема указывает на пробелы в миграции; Комментатор предлагает, чтобы проблема заслуживала более четкой документации.
  • Проблема предполагает наличие миграционных пробелов; Комментатор предлагает, чтобы проблема заслуживала более четкой документации.

Обсуждения (примечание: мы просим разрешения у авторов включить их работы в документацию):

  • Руководство по выводу средств IBC USDT № 1141 (https://github.com/gonka-ai/gonka/discussions/1141): Руководство по выводу средств IBC USDT Написанное пользователем руководство, которое можно перенести в документацию.
  • Написанное пользователем руководство, которое можно перенести в документацию.
  • Практическое руководство: Создайте и подайте предложение по управлению на Gonka # 1116 (https://github.com/gonka-ai/gonka/discussions/1116): ПАКТИЧЕСКОЕ РУКОВОДСТВО: Создайте и подайте предложение по управлению на Gonka Написанное пользователем руководство, которое можно перенести в документацию.
  • Написанное пользователем руководство, которое можно перенести в документацию.
  • Планируется ли добавить конфиденциальность на оперативном уровне для хостов? #796 (https://github.com/gonka-ai/gonka/discussions/796): Планируется ли добавить конфиденциальность на уровне подсказки для хостов? Документы могут прояснить текущее состояние TEE. Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.
  • Документы могут прояснить текущее состояние TEE. Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.
Русский перевод
heitor-lassarote avatar
heitor-lassaroteАвтор

Всем привет. Мы — команда Serokell (https://serokell.io/), и после прочтения дорожной карты сети сообщества Gonka (https://docs.google.com/document/d/1wPXTM40CnXyd8Hz_dvf7H1n6KQDqjw0RzppMx92xR8U/edit?pli=1&tab=t.0#heading=h.wt1svxjuy5ac), мы хотели обсудить трек 4, проект 3, озаглавленный «Сетевая документация», который имеет следующее описание по состоянию на 06.09.2026:

Структурированная система документации для хостов, разработчиков, внешних участников и команд экосистемы.

Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.

К этому проекту следует относиться как к постоянному процессу ведения документации, а не как к разовой работе по ее написанию. Он может поддерживать группу разработчиков документации или технических специалистов, ответственную за поддержание актуальности документации после обновлений протокола, инцидентов, повторяющихся вопросов поддержки и эксплуатационных изменений.

Метрики:

  • ПЕРВИЧНЫЙ: надежность и доверие сети.
  • ВТОРИЧНЫЙ: более низкая нагрузка на поддержку; более быстрая регистрация хоста.

Что это дает сети:

Gonka получает четкую, поддерживаемую и версионируемую базу знаний. Хозяева и внешние команды получают меньше двусмысленных инструкций и более безопасный путь при обновлении и операционных изменениях.

Мы хотели бы предложить команду для работы над структурированной документацией. В частности, мы хотели бы предложить следующие улучшения существующей документации:

  • Внедрите агента искусственного интеллекта для ответа на вопросы, связанные с документацией. Существует несколько вариантов владения/финансирования агента: Финансируется сообществом (пул сообщества): постоянный бюджет на хостинг и обслуживание. Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры». Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу. Варианты хостинга: Самостоятельное размещение на Gonka infra: требуется владение операционной системой. Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу. Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера. Выбор модели: начните с экономически эффективной модели: компромисс между качеством, задержкой и ценой. Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины. Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д. Защита от вредоносных и несвязанных запросов: на данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки. По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций. Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • Существует несколько вариантов владения/финансирования агента: Финансируется сообществом (пул сообщества): текущий бюджет на хостинг и обслуживание. Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры». Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Финансируется сообществом (пул сообщества): постоянный бюджет на хостинг и обслуживание.
  • Основана основная команда (gonka-ai): рассматривается как часть «документации как инфраструктуры».
  • Финансируется поставщиком (Serokell): мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Варианты хостинга: Самостоятельное размещение на Gonka infra: требуется владение операционной системой. Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу. Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера.
  • Самостоятельное размещение на Gonka infra: требуется владение операционной системой.
  • Размещено на инфраструктуре Serokell: мы будем финансировать его на начальном этапе с планом передачи сообществу.
  • Размещается через сеть Gonka, основанную на логических выводах: это в основном спекулятивный вариант, зависящий от осуществимости, бюджета и оперативной проверки. Требуется прогнозный бюджет сети/провайдера.
  • Выбор модели: начните с экономически эффективной модели: компромисс между качеством, задержкой и ценой. Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины. Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Начните с экономичной модели: компромисс между качеством, задержкой и ценой.
  • Сохраняйте модели на основе RAG (поисковая дополненная генерация): убедитесь, что документы (и, возможно, сам репозиторий Gonka) используются в качестве источника истины.
  • Добавьте набор оценок (50–100 реальных вопросов), чтобы оценить качество ответов. Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок. Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов. Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Используйте более сильную модель для оценки ответов на основе заранее определенных ожидаемых ответов со средней точностью по точкам с несколькими оценками (с использованием вопроса, ответа и фрагмента документации для оценки). Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок.
  • Чтобы бороться с предвзятостью, мы можем передать исходный фрагмент вместе с вопросами и ответами, а чтобы бороться с вариациями, один из планов — запустить один и тот же процесс оценки несколько раз в каждом тесте и взять среднее значение оценок.
  • Убедитесь, что агент находит правильные страницы документации для ожидаемых ответов.
  • Рассмотрите метрики для поиска правильной документации, такие как Recall@k, Hit@k, средний обратный ранг (MRR) и т. д.
  • Защита от вредоносных и несвязанных запросов: на данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки. По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций. Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • На данный момент мы не планируем никакого доступа к внутренним инструментам, кроме поиска в документации. Мы не видим, чтобы пользователь мог создавать вредоносные подсказки.
  • По несвязанным вопросам реализуем детектирование и защиту от оперативных инъекций.
  • Однако немедленная инъекция — это мягкое ограничение, которое невозможно полностью предотвратить. Для жестких ограничений мы планируем другие критерии, такие как максимальное количество запросов в минуту, максимально допустимое количество входных и выходных токенов, бюджет извлечения (чтобы предотвратить взрывной поиск, если запрос соответствует слишком большому количеству документов), бюджет истории разговоров (не подавать всю историю разговоров, если она стала слишком большой, возможно, заменив ее сводкой) и т. д.
  • Версионная документация. В данный момент может использоваться более одной сетевой версии. Переключатель, позволяющий выбрать чтение документации для конкретной версии, поможет аудитории, которая не находится в одной сети или версии программного обеспечения в одно и то же время. Похоже, что у Gonka есть поддерживаемая тестовая сеть, но доступность может контролироваться/основаться на запросах. Таким образом, версионные документы могут учитывать не только версию, но и сеть. Один из возможных планов — согласовать версию документации с тегами/ветвями выпуска GitHub. Документацию для версии следует получить на основе тега. Также может потребоваться управление версиями для конкретной сети. Сопровождающие и разработчики должны координировать усилия по поддержанию актуальности документации. Одним из вариантов помощи является использование агента в gonka-docs для отслеживания последних различий в репозитории gonka с основной веткой, в которой следует изменить gonka-docs. Однако этот вариант требует кредитов, и при больших различиях (обычно в gonka) результаты могут быть посредственными. Мы предлагаем провести эксперимент и проверить, как это будет происходить.
  • Похоже, что у Gonka есть поддерживаемая тестовая сеть, но доступность может контролироваться/основаться на запросах. Таким образом, версионные документы могут учитывать не только версию, но и сеть.
  • Один из возможных планов — согласовать версию документации с тегами/ветвями выпуска GitHub. Документацию для версии следует получить на основе тега. Также может потребоваться управление версиями для конкретной сети.
  • Сопровождающие и разработчики должны координировать усилия по поддержанию актуальности документации. Одним из вариантов помощи является использование агента в gonka-docs для отслеживания последних различий в репозитории gonka с основной веткой, в которой следует изменить gonka-docs. Однако этот вариант требует кредитов, и при больших различиях (обычно в gonka) результаты могут быть посредственными. Мы предлагаем провести эксперимент и проверить, как это будет происходить.
  • Автоматический перевод на другие языки. После улучшения агента искусственного интеллекта документация Gonka теперь написана на английском и китайском языках. Используя английскую версию в качестве источника истины, мы можем добавить третий вариант, позволяющий автоматически переводить на другие языки. Каждый переведенный документ будет ссылаться на исходный документ на английском языке. Тестирование будет проводиться модельным судьей с использованием репрезентативных языковых групп (русского, китайского и т. д.). Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее. Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Каждый переведенный документ будет ссылаться на исходный документ на английском языке.
  • Тестирование будет проводиться модельным судьей с использованием репрезентативных языковых групп (русского, китайского и т. д.). Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее. Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Что представляет собой репрезентативные языки сообщества гонка, следует обсудить далее.
  • Кроме того, мы можем предоставить LLM полуручно подобранный набор терминов и их переводов для более единообразных переводов и более высокой точности перевода. Это потребует участия переводчиков-носителей языка для проверки этого набора на целевом языке.
  • Метрики и телеметрия для поиска документов и посещений страниц. Использование документации: Просмотров на страницу: отслеживайте основные точки входа и критические пути. Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался». Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики. Поисковая телеметрия: поисковые запросы (анонимные): обнаруживайте недостающие темы и запутанную терминологию. Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить. Запрос → результат клика: измеряйте релевантность поиска и качество навигации. Отслеживание качества: «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы. Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий. Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером. Поддержка: Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации. Хостинг: Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Использование документации: Просмотров на страницу: отслеживайте основные точки входа и критические пути. Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался». Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики.
  • Просмотров на страницу: отслеживайте основные точки входа и критические пути.
  • Время, затраченное на страницу, и глубина прокрутки: определите страницы с быстрыми ответами или страницы с быстрыми ответами. «прочитал, но запутался».
  • Коэффициент выхода и навигация по следующей странице: смотрите, куда пользователи идут дальше, и находите тупики.
  • Поисковая телеметрия: поисковые запросы (анонимные): обнаруживайте недостающие темы и запутанную терминологию. Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить. Запрос → результат клика: измеряйте релевантность поиска и качество навигации.
  • Поисковые запросы (анонимные): найдите недостающие темы и запутанную терминологию.
  • Поиски с нулевым результатом: выявите самые большие пробелы, которые нужно заполнить.
  • Запрос → результат клика: измеряйте релевантность поиска и качество навигации.
  • Отслеживание качества: «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы. Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий. Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером.
  • «Было ли это полезно?» голоса + необязательные теги причин: найдите устаревшие или непонятные страницы.
  • Обнаружение неработающих ссылок и ошибок 404: своевременное и автоматическое обнаружение регрессий.
  • Сигналы несоответствия версий: найдите пользователей, переходящих на неправильные версии, возможно, отслеживаемые реферером.
  • Поддержка: Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации.
  • Ссылки на проблемы/обсуждения GitHub: позволяют перенаправлять пользователей на систему отслеживания проблем GitHub или обсуждения из документации.
  • Хостинг: Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Как и в случае с агентом ИИ, хостинг может осуществляться с помощью Gonka infra или Serokell infra на начальном этапе с последующей передачей сообществу.
  • Проведите аудит и разрешите предложенные проблемы/обсуждения/комментарии по связям с общественностью относительно документации в репозитории Gonka, представленные в разделе «Проблемы, связанные с документацией, запросы на запросы и обсуждения» ниже. Они будут использоваться в качестве исходных данных для улучшения документации.
  • Найдите и перенесите соответствующую документацию из репозитория кода в репозиторий документации.

График поддержки вышеуказанного плана может выглядеть следующим образом:

  • Создайте инфраструктуру и внедрите метрики и телеметрию для документации.
  • Внедрите функцию управления версиями документов и напишите для нее тесты.
  • (Пере)писать документацию на основе предложенного списка вопросов и обсуждений.
  • Найдите и перенесите соответствующую документацию из репозитория кода в репозиторий документации.
  • Разработайте и интегрируйте агента ИИ, используя репозиторий знаний gonka-ai/gonka-docs (https://github.com/gonka-ai/gonka-docs), и добавьте его в https://gonka.ai/docs/, добавив новую кнопку, например «Спросить агента».
  • Создайте набор оценок и проверьте качество ответов.
  • Используя ранее реализованный AI-агент, поддержите новый переключатель, помимо английского и китайского, например «Другое (автоперевод)».
  • Создавайте оценки переведенного контента.
  • Напишите план, четко описывающий, как передать эти новые функции сообществу Gonka.
  • Целевой моделью является постоянное техническое обслуживание. Если финансирование ограничено, первоначальный объем может включать единовременную начальную загрузку и план передачи.

Проблемы, связанные с документацией, PR и обсуждения

Соответствующие PR:

  • документы: добавьте переводы на китайский (zh) для ключевой документации № 1327 (https://github.com/gonka-ai/gonka/pull/1327) : docs: добавьте переводы на китайский (zh) для ключевой документации Не объединено, предложено в неправильном репозитории.
  • Не объединено, предложено в неправильном репозитории.

Соответствующие вопросы:

  • Как получить ключ API брокера для node4 (или документацию по процессу регистрации брокера)? #1331 (https://github.com/gonka-ai/gonka/issues/1331): Как получить ключ API брокера для node4 (или документацию по процессу регистрации брокера)? Открытая проблема с запросом документации.
  • Открытая проблема с запросом документации.
  • Поток самообслуживания (без брокера) задокументирован как рабочий, но возвращает 401 «модель требует ключ API» — я хочу потратить свой собственный GNK напрямую # 1319 (https://github.com/gonka-ai/gonka/issues/1319): Поток самообслуживания (без брокера) документирован как рабочий, но возвращает 401 «модель требует ключ API» — я хочу потратить свой собственный GNK напрямую Запрашивает изменения кода, но предполагает, что документы могут быть более ясными.
  • Запрашивает изменения кода, но предлагает, чтобы документация была более понятной.
  • Запустить перевод документации Gonka на Gonka gonka-docs#1149 (https://github.com/gonka-ai/gonka-docs/issues/1149): Запустить перевод документации Gonka на Gonka. Один из предлагаемых нами рабочих пунктов, касающихся автоматического перевода.
  • Один из предложенных нами пунктов работы касается автоматического перевода.
  • Вопрос: есть ли возможность использовать графические процессоры потребительского уровня с объемом памяти 16 ГБ в качестве облегченных хост-узлов? #1032 (https://github.com/gonka-ai/gonka/issues/1032): Вопрос: есть ли возможность использовать графические процессоры потребительского уровня с 16 ГБ памяти в качестве облегченных хост-узлов? Проблема была преобразована в беседу, доступную только соавторам, и на нее нет ответа.
  • Проблема была преобразована в беседу, доступную только соавторам, и на нее нет ответа.
  • Регистрация узла не обновляется после миграции (API зависает с использованием старой конфигурации цепочки) # 447 (https://github.com/gonka-ai/gonka/issues/447): Регистрация узла не обновляется после миграции (API зависает с использованием старой конфигурации цепочки). Проблема указывает на пробелы в миграции; Комментатор предлагает, чтобы проблема заслуживала более четкой документации.
  • Проблема предполагает наличие миграционных пробелов; Комментатор предлагает, чтобы проблема заслуживала более четкой документации.

Обсуждения (примечание: мы просим разрешения у авторов включить их работы в документацию):

  • Руководство по выводу средств IBC USDT № 1141 (https://github.com/gonka-ai/gonka/discussions/1141): Руководство по выводу средств IBC USDT Написанное пользователем руководство, которое можно перенести в документацию.
  • Написанное пользователем руководство, которое можно перенести в документацию.
  • Практическое руководство: Создайте и подайте предложение по управлению на Gonka # 1116 (https://github.com/gonka-ai/gonka/discussions/1116): ПАКТИЧЕСКОЕ РУКОВОДСТВО: Создайте и подайте предложение по управлению на Gonka Написанное пользователем руководство, которое можно перенести в документацию.
  • Написанное пользователем руководство, которое можно перенести в документацию.
  • Планируется ли добавить конфиденциальность на оперативном уровне для хостов? #796 (https://github.com/gonka-ai/gonka/discussions/796): Планируется ли добавить конфиденциальность на уровне подсказки для хостов? Документы могут прояснить текущее состояние TEE. Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.
  • Документы могут прояснить текущее состояние TEE. Документация должна иметь четкий канонический источник в общедоступном репозитории документации GitHub, где изменения можно просматривать, версионировать и обновлять с помощью PR.
Оригинал
heitor-lassarote avatar
heitor-lassaroteАвтор

Hello, everyone. We’re a team at Serokell (https://serokell.io/) , and after reading the Gonka Community Network Roadmap (https://docs.google.com/document/d/1wPXTM40CnXyd8Hz_dvf7H1n6KQDqjw0RzppMx92xR8U/edit?pli=1&tab=t.0#heading=h.wt1svxjuy5ac) , we wanted to discuss Track 4, Project 3, entitled “Network documentation”, which has the following description as of 09-06-2026:

A structured documentation system for hosts, developers, external contributors, and ecosystem teams.

The documentation should have a clear canonical source in a public GitHub documentation repository, where changes can be reviewed, versioned, and updated through PRs.

This project should be treated as an ongoing documentation maintenance process, not a one-time writing effort. It could support a documentation or technical writing team responsible for keeping the documentation up to date after protocol upgrades, incidents, recurring support questions, and operational changes.

Metrics:

  • PRIMARY: network reliability and trust.
  • SECONDARY: lower support burden; faster host onboarding.

What this gives the network:

Gonka gets a clear, maintained, and versioned knowledge base. Hosts and external teams get fewer ambiguous instructions and a safer path through upgrades and operational changes.

We would like to offer a team to work on the structured documentation. In particular, we’d like to offer the following improvements to the existing documentation:

  • Implement an AI agent to answer docs-related questions: There are multiple choices for the ownership/funding of the agent: Community-funded (community pool): ongoing budget for hosting and maintenance. Core-team founded (gonka-ai): treated as part of “docs as infrastructure”. Vendor-funded (Serokell): we’d fund it during the initial phase, with a handover plan to the community. Hosting options: Self-hosted on Gonka infra: requires ops ownership. Hosted on Serokell infra: we’d fund it during the initial phase, with a handover plan to the community. Hosted via Gonka inference-based network: this is mostly speculative, subject to feasibility, budget, and ops validation. Requires an inference budget on the network/provider. Model choice: Start with a cost-effective model: quality, latency, and price trade-off. Keep models RAG-based (Retrieval-Augmented Generation): ensure the docs (and possibly the Gonka repo itself) are used as source of truth. Add an evaluation set (50–100 real questions) to measure answer quality. Use a stronger model to judge the answers based on predefined expected answers, with average Pointwise accuracy with several estimates (using question, answer, and documentation fragment for judging). To fight bias, we may feed the original fragment along with question and answer, and to fight variation, one plan is to run the same scoring process several times on each test and take the average of the scores. Assert that the agent finds the correct documentation pages for expected answers. Consider metrics for finding the correct documentation, such as Recall@k, Hit@k, Mean Reciprocal Rank (MRR), etc.. Protection against harmful and unrelated requests: For now, we don’t plan any access to internal tooling, apart from searching in the docs. We don’t see a way that the user could create harmful prompts. As for unrelated questions, we’ll implement detection and protection against prompt injections. However, prompt injection is a soft restriction that cannot be fully prevented. For hard restrictions, we plan other criteria, such as maximum amount of requests per minute, maximum allowed input and output tokens, retrieval budget (to prevent a retrieval explosion if a query matches too many documents), conversation history budget (do not feed the entire conversation history if it grew too large, perhaps replacing it with a summary), etc..
  • There are multiple choices for the ownership/funding of the agent: Community-funded (community pool): ongoing budget for hosting and maintenance. Core-team founded (gonka-ai): treated as part of “docs as infrastructure”. Vendor-funded (Serokell): we’d fund it during the initial phase, with a handover plan to the community.
  • Community-funded (community pool): ongoing budget for hosting and maintenance.
  • Core-team founded (gonka-ai): treated as part of “docs as infrastructure”.
  • Vendor-funded (Serokell): we’d fund it during the initial phase, with a handover plan to the community.
  • Hosting options: Self-hosted on Gonka infra: requires ops ownership. Hosted on Serokell infra: we’d fund it during the initial phase, with a handover plan to the community. Hosted via Gonka inference-based network: this is mostly speculative, subject to feasibility, budget, and ops validation. Requires an inference budget on the network/provider.
  • Self-hosted on Gonka infra: requires ops ownership.
  • Hosted on Serokell infra: we’d fund it during the initial phase, with a handover plan to the community.
  • Hosted via Gonka inference-based network: this is mostly speculative, subject to feasibility, budget, and ops validation. Requires an inference budget on the network/provider.
  • Model choice: Start with a cost-effective model: quality, latency, and price trade-off. Keep models RAG-based (Retrieval-Augmented Generation): ensure the docs (and possibly the Gonka repo itself) are used as source of truth. Add an evaluation set (50–100 real questions) to measure answer quality. Use a stronger model to judge the answers based on predefined expected answers, with average Pointwise accuracy with several estimates (using question, answer, and documentation fragment for judging). To fight bias, we may feed the original fragment along with question and answer, and to fight variation, one plan is to run the same scoring process several times on each test and take the average of the scores. Assert that the agent finds the correct documentation pages for expected answers. Consider metrics for finding the correct documentation, such as Recall@k, Hit@k, Mean Reciprocal Rank (MRR), etc..
  • Start with a cost-effective model: quality, latency, and price trade-off.
  • Keep models RAG-based (Retrieval-Augmented Generation): ensure the docs (and possibly the Gonka repo itself) are used as source of truth.
  • Add an evaluation set (50–100 real questions) to measure answer quality. Use a stronger model to judge the answers based on predefined expected answers, with average Pointwise accuracy with several estimates (using question, answer, and documentation fragment for judging). To fight bias, we may feed the original fragment along with question and answer, and to fight variation, one plan is to run the same scoring process several times on each test and take the average of the scores. Assert that the agent finds the correct documentation pages for expected answers. Consider metrics for finding the correct documentation, such as Recall@k, Hit@k, Mean Reciprocal Rank (MRR), etc..
  • Use a stronger model to judge the answers based on predefined expected answers, with average Pointwise accuracy with several estimates (using question, answer, and documentation fragment for judging). To fight bias, we may feed the original fragment along with question and answer, and to fight variation, one plan is to run the same scoring process several times on each test and take the average of the scores.
  • To fight bias, we may feed the original fragment along with question and answer, and to fight variation, one plan is to run the same scoring process several times on each test and take the average of the scores.
  • Assert that the agent finds the correct documentation pages for expected answers.
  • Consider metrics for finding the correct documentation, such as Recall@k, Hit@k, Mean Reciprocal Rank (MRR), etc..
  • Protection against harmful and unrelated requests: For now, we don’t plan any access to internal tooling, apart from searching in the docs. We don’t see a way that the user could create harmful prompts. As for unrelated questions, we’ll implement detection and protection against prompt injections. However, prompt injection is a soft restriction that cannot be fully prevented. For hard restrictions, we plan other criteria, such as maximum amount of requests per minute, maximum allowed input and output tokens, retrieval budget (to prevent a retrieval explosion if a query matches too many documents), conversation history budget (do not feed the entire conversation history if it grew too large, perhaps replacing it with a summary), etc..
  • For now, we don’t plan any access to internal tooling, apart from searching in the docs. We don’t see a way that the user could create harmful prompts.
  • As for unrelated questions, we’ll implement detection and protection against prompt injections.
  • However, prompt injection is a soft restriction that cannot be fully prevented. For hard restrictions, we plan other criteria, such as maximum amount of requests per minute, maximum allowed input and output tokens, retrieval budget (to prevent a retrieval explosion if a query matches too many documents), conversation history budget (do not feed the entire conversation history if it grew too large, perhaps replacing it with a summary), etc..
  • Versioned documentation. There might be more than one network version being used at a given moment. A switch allowing choosing to read the documentation for a specific version would aid audiences who are not on the same network or software version at the same time. Gonka appears to have a maintained testnet, but accessibility may be controlled/request-based. So versioned docs may account for not just the version, but also the network. One possible plan is to align docs version with GitHub release tags/branches. The documentation for the version should be fetched based on the tag. Network-specific versioning may also be needed. The maintainers and developers should coordinate efforts to keep the documentation up-to-date. One option to aid is to use an agent in gonka-docs to monitor recent diffs in the gonka repo against the main branch in which gonka-docs should be changed. This option, however, requires credits, and for large diffs (common in gonka ) may produce mediocre results. We propose to make an experiment and test how this would go.
  • Gonka appears to have a maintained testnet, but accessibility may be controlled/request-based. So versioned docs may account for not just the version, but also the network.
  • One possible plan is to align docs version with GitHub release tags/branches. The documentation for the version should be fetched based on the tag. Network-specific versioning may also be needed.
  • The maintainers and developers should coordinate efforts to keep the documentation up-to-date. One option to aid is to use an agent in gonka-docs to monitor recent diffs in the gonka repo against the main branch in which gonka-docs should be changed. This option, however, requires credits, and for large diffs (common in gonka ) may produce mediocre results. We propose to make an experiment and test how this would go.
  • Automatic translation to other languages. Following the AI agent improvement, the Gonka docs are currently written in English and Chinese. Using the English version as the source of truth, we may add a third option allowing for automatic translation to other languages. Every translated document will link to the original English document. Testing will be done with the model judge using representative language groups (Russian, Chinese, etc.). What constitutes representative languages of the Gonka community should be discussed further. In addition, we may provide the LLM with a semi-manually curated set of terms and their translations for more consistent translations and higher translation accuracy. This will require input from native human translators to validate this set for a target language.
  • Every translated document will link to the original English document.
  • Testing will be done with the model judge using representative language groups (Russian, Chinese, etc.). What constitutes representative languages of the Gonka community should be discussed further. In addition, we may provide the LLM with a semi-manually curated set of terms and their translations for more consistent translations and higher translation accuracy. This will require input from native human translators to validate this set for a target language.
  • What constitutes representative languages of the Gonka community should be discussed further.
  • In addition, we may provide the LLM with a semi-manually curated set of terms and their translations for more consistent translations and higher translation accuracy. This will require input from native human translators to validate this set for a target language.
  • Metrics and telemetry for docs searches and page hits. Documentation usage: Views per page: track the top entry points and critical paths. Time spent on page and scroll depth: detect pages with quick answers vs. “read but confused”. Exit rate and next-page navigation: see where users go next and spot dead ends. Search telemetry: Search queries (anonymized): discover missing topics and confusing terminology. Zero-result searches: detect biggest gaps to fill. Query → clicked result: measure search relevance and navigation quality. Quality tracking: “Was this helpful?” votes + optional reason tags: find outdated or unclear pages. Broken links/404s detection: catch regressions early and automatically. Version mismatch signals: find users landing on wrong versions, possibly tracked by referrer. Support: Links to GitHub issues/discussions: allow redirecting users to the GitHub issue tracker or discussions from the docs. Hosting: As with the AI agent, the hosting may be done with Gonka infra, or in Serokell infra during an initial phase with a later handover plan to the community.
  • Documentation usage: Views per page: track the top entry points and critical paths. Time spent on page and scroll depth: detect pages with quick answers vs. “read but confused”. Exit rate and next-page navigation: see where users go next and spot dead ends.
  • Views per page: track the top entry points and critical paths.
  • Time spent on page and scroll depth: detect pages with quick answers vs. “read but confused”.
  • Exit rate and next-page navigation: see where users go next and spot dead ends.
  • Search telemetry: Search queries (anonymized): discover missing topics and confusing terminology. Zero-result searches: detect biggest gaps to fill. Query → clicked result: measure search relevance and navigation quality.
  • Search queries (anonymized): discover missing topics and confusing terminology.
  • Zero-result searches: detect biggest gaps to fill.
  • Query → clicked result: measure search relevance and navigation quality.
  • Quality tracking: “Was this helpful?” votes + optional reason tags: find outdated or unclear pages. Broken links/404s detection: catch regressions early and automatically. Version mismatch signals: find users landing on wrong versions, possibly tracked by referrer.
  • “Was this helpful?” votes + optional reason tags: find outdated or unclear pages.
  • Broken links/404s detection: catch regressions early and automatically.
  • Version mismatch signals: find users landing on wrong versions, possibly tracked by referrer.
  • Support: Links to GitHub issues/discussions: allow redirecting users to the GitHub issue tracker or discussions from the docs.
  • Links to GitHub issues/discussions: allow redirecting users to the GitHub issue tracker or discussions from the docs.
  • Hosting: As with the AI agent, the hosting may be done with Gonka infra, or in Serokell infra during an initial phase with a later handover plan to the community.
  • As with the AI agent, the hosting may be done with Gonka infra, or in Serokell infra during an initial phase with a later handover plan to the community.
  • Audit, and resolve the proposed issues/discussions/PR comments regarding documentation in the Gonka repository, provided in “Documentation-Related Issues, PRs, and Discussions” below. They will be used as the input for docs improvements.
  • Discover and migrate relevant documentation from the code repo into the docs repo.

The schedule to support the above plan might look like this:

  • Create the infrastructure and implement metrics and telemetry for the documentation.
  • Implement the versioned docs feature and write tests for it.
  • (Re)write documentation based on the proposed list of issues and discussions.
  • Discover and migrate relevant documentation from the code repo into the docs repo.
  • Create the evaluation set and test the quality of the answers.
  • Using the AI agent implemented earlier, support a new toggle besides English and Chinese such as “Other (auto-translate)”.
  • Create evaluations for the translated content.
  • Write a plan clearly detailing how to hand these new features to the Gonka community.
  • Ongoing maintenance is the target model. If the funding is limited, the initial scope may be a one-time bootstrap plus the handover plan.

Documentation-Related Issues, PRs, and Discussions

Relevant PRs:

  • Unmerged, proposed in the wrong repo.

Relevant issues:

  • How to obtain a broker API key for node4 (or documentation on the broker onboarding process)? #1331 (https://github.com/gonka-ai/gonka/issues/1331) : How to obtain a broker API key for node4 (or documentation on the broker onboarding process)? Open issue requesting documentation.
  • Open issue requesting documentation.
  • Self-serve (no-broker) flow is documented as working but returns 401 "model requires an API key" — I want to spend my own GNK directly #1319 (https://github.com/gonka-ai/gonka/issues/1319) : Self-serve (no-broker) flow is documented as working but returns 401 "model requires an API key" — I want to spend my own GNK directly Requests code changes, but suggests the docs could be clearer.
  • Requests code changes, but suggests the docs could be clearer.
  • One of our proposed work points regarding automatic translation.
  • Question: is there a path for consumer-grade 16 GB GPUs to participate as lightweight Host nodes? #1032 (https://github.com/gonka-ai/gonka/issues/1032) : Question: is there a path for consumer-grade 16 GB GPUs to participate as lightweight Host nodes? Issue was converted to a conversation, limited to collaborators, and has no answer.
  • Issue was converted to a conversation, limited to collaborators, and has no answer.
  • Node Registration Does Not Update After Migration (API stuck using old on-chain config) #447 (https://github.com/gonka-ai/gonka/issues/447) : Node Registration Does Not Update After Migration (API stuck using old on-chain config) Issue suggests migration gaps; commenter suggests the issue deserver clearer documentation.
  • Issue suggests migration gaps; commenter suggests the issue deserver clearer documentation.

Discussions (n.b.: we’d ask for permission from the authors to include their work in the docs):

  • User-written guide that could be migrated to the docs.
  • User-written guide that could be migrated to the docs.
  • Are there plans to add prompt-level confidentiality for hosts? #796 (https://github.com/gonka-ai/gonka/discussions/796) : Are there plans to add prompt-level confidentiality for hosts? Docs could clarify the current state of TEE.The documentation should have a clear canonical source in a public GitHub documentation repository, where changes can be reviewed, versioned, and updated through PRs.
  • Docs could clarify the current state of TEE.The documentation should have a clear canonical source in a public GitHub documentation repository, where changes can be reviewed, versioned, and updated through PRs.