playfetch

PlayFetch

PlayFetch позволяет быстро и безболезненно добавлять функции большой языковой модели в ваше приложение.

Фон

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

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

Что такое PlayFetch?

• Интуитивно понятная игровая площадка, построенная на совместной работе с комментариями, аннотациями, метками и оценками.
• Неразрушающая система управления версиями, которую может прозрачно использовать любой член команды.
• Среда тестирования с импортом и экспортом данных, цепочками измерений и автоматическим тестированием чат-ботов.
• Платформа LLM, которая легко интегрируется с инструментами для контроля исходного кода, управления проектами и векторными хранилищами.
• Независимое от модели решение для хостинга с простым унифицированным API, поддерживающим простые вызовы, чат и ручные прерывания.
• Решение для аналитики и мониторинга, ориентированное на потребности в функциях LLM.

Развертывание PlayFetch в Google Cloud

PlayFetch оптимизирован для работы на Google Cloud Platform. Следуйте инструкциям ниже, чтобы запустить собственный экземпляр. Мы предполагаем, что вы создали форк официального репозитория PlayFetch по адресу https://github.com/yello-xyz/playfetch (чтобы вы могли настроить непрерывную интеграцию). Если вы планируете внести изменения в код, вы можете выполнить эти инструкции несколько раз, чтобы настроить отдельные экземпляры для разработки, подготовки и производства.

Настроить новый проект

• Настройте свою учетную запись Google Cloud Platform на https://cloud.google.com/.
• Откройте облачную консоль по адресу https://console.cloud.google.com.
• Перейдите в IAM & Admin → Управление ресурсами и нажмите СОЗДАТЬ ПРОЕКТ .
• Выберите уникальное имя (нельзя изменить позже) и нажмите СОЗДАТЬ .
• Перейдите в раздел «Оплата» и в разделе «Управление учетной записью » убедитесь, что для нового проекта включена оплата.

Настройка API

• Перейдите в раздел «API и службы» → «Включенные API и службы» .
• Убедитесь, что вновь созданный проект выбран в селекторе проектов вверху.
• Нажмите ВКЛЮЧИТЬ APIS И СЕРВИСЫ .
• Найдите App Engine Admin API и нажмите ВКЛЮЧИТЬ .
• Найдите Cloud Build API и нажмите ВКЛЮЧИТЬ .
• Найдите Cloud Datastore API и нажмите ВКЛЮЧИТЬ .
• Найдите Cloud Scheduler API и нажмите ВКЛЮЧИТЬ .
• Найдите Гибкую среду Google App Engine и нажмите ВКЛЮЧИТЬ .
• Найдите API управления идентификацией и доступом (IAM) и нажмите ВКЛЮЧИТЬ .
• Найдите Vertex AI API и нажмите ВКЛЮЧИТЬ .

Настройка приложения App Engine

• Перейдите в App Engine → Панель инструментов и нажмите СОЗДАТЬ ПРИЛОЖЕНИЕ .
• Выберите местоположение (нельзя изменить позже).
• Оставьте параметр учетной записи службы открытым (мы будем использовать значение по умолчанию) и нажмите «ДАЛЕЕ» .
• Не обращайте внимания на панель развертывания (нажмите Я СДЕЛАЮ ЭТО ПОЗЖЕ ).

Настройка хранилища данных

• Перейдите в хранилище данных .
• Если вы не видите хранилище данных (по умолчанию) , подождите минуту и ​​обновите его.
• Выберите хранилище данных (по умолчанию) .
• Выберите Срок жизни (TTL) на боковой панели и нажмите СОЗДАТЬ ПОЛИТИКУ .
• Установите для Kind значение _nextauth_token и для свойства Timestamp значение expires и нажмите CREATE .
• Создайте еще одну политику с добрым кешем и свойством expiresAt .

Настройка сегмента хранилища

• Перейдите в Cloud Storage → Buckets и выберите сегмент [имя проекта] .appspot.com .
• В разделе РАЗРЕШЕНИЯ нажмите ПРЕДОСТАВИТЬ ДОСТУП .
• Добавьте участника allUsers и назначьте роль Storage Object Viewer .
• Нажмите СОХРАНИТЬ и РАЗРЕШИТЬ ПУБЛИЧНЫЙ ДОСТУП (это ведро будет использоваться для хранения аватаров).

Создайте учетную запись службы сборки

• Перейдите в IAM & Admin → Сервисные учетные записи и нажмите СОЗДАТЬ СЕРВИСНЫЙ АККАУНТ .
• Выберите уникальное имя и нажмите СОЗДАТЬ И ПРОДОЛЖИТЬ .
• Выберите роль «Пользователь учетной записи службы» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «App Engine Deployer» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «Агент службы гибкой среды App Engine» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «Администратор службы App Engine» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «Учетная запись Cloud Build Service» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «Администратор индекса Cloud Datastore» .
• Нажмите «ДОБАВИТЬ ДРУГУЮ РОЛЬ» и выберите «Администратор Cloud Scheduler» .
• Нажмите ПРОДОЛЖИТЬ и ГОТОВО .

[необязательно] Настройка личного домена

• Перейдите в App Engine → Настройки .
• В разделе «ПОЛЬЗОВАТЕЛЬСКИЕ ДОМЕНЫ» нажмите «ДОБАВИТЬ ПОЛЬЗОВАТЕЛЬСКИЙ ДОМЕН» .
• Введите личный домен и субдомены, которые вы хотите использовать (следуя инструкциям по подтверждению права собственности).
• Нажмите ПРОДОЛЖИТЬ и ГОТОВО .
• Добавьте показанные записи в конфигурацию DNS вашего поставщика личного домена.

[необязательно, но рекомендуется] Настройте аутентификацию пользователя Google OAuth.

• Перейдите в раздел «API и службы» → «Экран согласия OAuth» .
• Выберите тип пользователя «Внутренний» или «Внешний» в зависимости от вашего варианта использования и нажмите «СОЗДАТЬ» .
• Заполните необходимые поля, нажмите СОХРАНИТЬ И ПРОДОЛЖИТЬ , затем нажмите ДОБАВИТЬ ИЛИ УДАЛИТЬ ОБЛАСТИ .
• Проверьте область .../auth/userinfo.profile и .../auth/userinfo.email , затем нажмите ОБНОВИТЬ и СОХРАНИТЬ И ПРОДОЛЖИТЬ .
• Если вы выбрали внешний тип пользователя выше, вы можете добавить несколько тестовых учетных записей (перед публикацией приложения в рабочей среде). Обязательно укажите адрес электронной почты, который вы хотите использовать для своего первого администратора. Обратите внимание, что вам все равно нужно будет предоставить этим пользователям доступ в PlayFetch.
• Нажмите СОХРАНИТЬ И ПРОДОЛЖИТЬ и ВЕРНУТЬСЯ НА ПАНЕЛЬ .
• Выберите «Учетные данные» на боковой панели, затем нажмите «СОЗДАТЬ УЧЕТНЫЕ ДАННЫЕ» и идентификатор клиента OAuth .
• Выберите «Веб-приложение» в качестве типа приложения и выберите имя.
• В разделе «Авторизованные источники JavaScript» добавьте https:// [имя проекта] .appspot.com (и личный домен, если он у вас есть). Если вы также хотите использовать аутентификацию Google при локальном запуске приложения, добавьте также http://localhost:3000 .
• В разделе «Разрешенные URI перенаправления» добавьте https:// [project-name] .appspot.com/api/auth/callback/google (и аналогичный URL-адрес для любого личного домена). Если вы также хотите использовать аутентификацию Google при локальном запуске приложения, добавьте также http://localhost:3000/api/auth/callback/google .
• Нажмите «СОЗДАТЬ» и скопируйте сгенерированные идентификатор клиента и секрет клиента, чтобы использовать их в настройке триггера сборки ниже.

Настройка сборки

• Перейдите в Cloud Build → Триггеры и нажмите ПОДКЛЮЧИТЬ РЕПОЗИТАРИЙ .
• Выберите исходный GitHub (приложение Cloud Build GitHub) и нажмите ПРОДОЛЖИТЬ , чтобы аутентифицировать учетную запись GitHub, в которой вы разветвили репозиторий (во всплывающем окне).
• Выберите раздвоенный репозиторий, установите флажок под ним и нажмите ПОДКЛЮЧИТЬСЯ .
• Нажмите СОЗДАТЬ ТРИГГЕР .
• Выберите имя для своей сборки.
• В разделе «Конфигурация» выберите файл конфигурации Cloud Build (yaml или json) .
• Для минимальной настройки вам нужно будет добавить следующие переменные подстановки в триггер сборки (в разделе «Дополнительно »), нажав «ДОБАВИТЬ ПЕРЕМЕННУЮ» :
  • _ENCRYPTION_KEY : случайная строка из 64 шестнадцатеричных цифр.
  • _NEXTAUTH_SECRET : случайная строка длиной не менее 32 символов.
  • _NEXTAUTH_URL : общедоступный URL-адрес вашего экземпляра, либо личный домен, если он у вас есть, либо https:// [project-name] .appspot.com .
  • _GCLOUD_STORAGE_BUCKET : имя сегмента облачного хранилища, к которому вы разрешили публичный доступ, например [имя проекта] .appspot.com .
  • _NOREPLY_EMAIL_USER и _NOREPLY_EMAIL_PASSWORD : учетная запись Gmail, которая будет использоваться для исходящих транзакционных электронных писем. Это может быть выделенная учетная запись в Google Workspace (с обычным паролем) или отдельная учетная запись Gmail (с паролем приложения). См. инструкции ниже, если вам нужно использовать другого поставщика услуг электронной почты.
• Если вы настроили аутентификацию Google выше, вам также следует добавить следующие переменные:
  • _GOOGLE_CLIENT_ID и _GOOGLE_CLIENT_SECRET : значения, которые вы скопировали выше после создания учетных данных OAuth.
• В разделе «Учетная запись службы» выберите учетную запись службы, которую вы создали выше.
• Нажмите СОЗДАТЬ .
• Нажмите «Выполнить» рядом с только что созданным триггером, а затем нажмите «Выполнить триггер».
• Выберите «История» на боковой панели и подождите, пока сборка завершится успешно (это может занять 10–15 минут).

Инициализируйте среду PlayFetch

• Выберите адрес электронной почты, который будет использоваться в качестве логина для первоначального пользователя-администратора.
• Откройте браузер и перейдите по адресу https:// [имя-проекта] .appspot.com/api/admin/init?admin= [[email protected]] (обязательно укажите правильный адрес электронной почты в запросе).
• Эта конечная точка запустит сценарий для инициализации хранилища данных (что может занять минуту), но вы сможете запустить его только один раз (если вы не создадите хранилище данных заново).
• После завершения сценария скопируйте значения для _PLAYFETCH_API_KEY и _PLAYFETCH_ENDPOINT_URL , показанные в ответе.
• Перейдите в Cloud Build → Triggers , щелкните созданный вами триггер, добавьте две дополнительные переменные замены из предыдущего шага и нажмите SAVE .
• Снова запустите триггер сборки с добавленными переменными. Возможно, при этой сборке потребуется создать недостающие индексы хранилища данных, поэтому лучше дождаться ее повторного завершения.

Теперь вы сможете перейти по адресу https:// [project-name] .appspot.com и войти в систему, используя адрес электронной почты, который вы указали для своего первого пользователя-администратора. Вы можете использовать либо аутентификацию Google (если она настроена), либо ссылки электронной почты (при условии, что переменные _NOREPLY_EMAIL настроены правильно). Дополнительным пользователям можно предоставить доступ в панели администратора.

Запуск PlayFetch локально

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

Установите узел и npm

Самый простой способ установить последнюю версию узла и npm — запустить последнюю версию установщика.

Клонировать репозиторий

Либо откройте с помощью GitHub Desktop и клонируйте в локальный каталог, либо подключитесь к GitHub с помощью SSH и запустите git clone [email protected]:yello-xyz/playfetch.git . Если вы уже разветвили репозиторий, вместо этого вы можете клонировать его.

Настройка среды

Чтобы запустить приложение локально, вам нужно будет добавить несколько таких же переменных в ваш локальный файл .env.local (этот файл игнорируется системой управления версиями во избежание утечки ключей). Это могут быть те же значения, которые вы указали в триггере сборки Google Cloud для вашего экземпляра разработки (при условии, что вы используете отдельный экземпляр для производства, поскольку вы не хотите рисковать утечкой этих ключей), за исключением _NEXTAUTH_URL , где следует указать значение http://localhost:3000.

Вы можете получить доступ к хранилищу данных в Google Cloud со своего локального компьютера (опять же при условии, что вы используете отдельный экземпляр разработки, чтобы случайно не повредить или не утечь производственные данные), установив Google Cloud CLI и инициализировав его, как описано здесь (вы можете пропустить остальные шаги). Выполните следующие команды, чтобы войти в свою учетную запись Google:

• gcloud auth login
• gcloud init
• gcloud auth application-default login
• gcloud init

Стройте и запускайте

Теперь вы сможете запускать следующие команды:

• npm install
• npm run build
• npm run start

Альтернативно, во время разработки вы можете просто запустить следующую команду, чтобы запустить отладочную сборку с быстрым обновлением:

npm run dev

Чтобы запустить все тесты один раз:

npm run test

Чтобы отслеживать изменения и автоматически перезапускать соответствующие наборы тестов:

npm run watch

Дополнительные функции

Чтобы расширить минимальную настройку, вы можете настроить следующие переменные среды (либо в триггере сборки GCP, либо в локальном файле .env.local), чтобы включить некоторые дополнительные функции.

Интеграции

• _GITHUB_CLIENT_ID , _GITHUB_CLIENT_SECRET : можно использовать для настройки аутентификации GitHub OAuth (аналогично Google). Требуется настройка приложения GitHub OAuth.
• _GITHUB_APP_CLIENT_ID , _GITHUB_APP_CLIENT_SECRET , _GITHUB_APP_ID , _GITHUB_APP_PRIVATE_KEY , _NEXT_PUBLIC_GITHUB_APP_INSTALL_LINK : можно использовать для настройки интеграции системы управления версиями. Требуется настройка приложения GitHub.
• _LINEAR_APP_CLIENT_ID , _LINEAR_APP_CLIENT_SECRET , _LINEAR_APP_WEBHOOK_SECRET : можно использовать для настройки интеграции управления задачами. Также требуется настройка приложения Linear.
• _NOTION_TOKEN, _NOTION_ONBOARDING_PAGE_ID, _NOTION_WAITLIST_PAGE_ID : могут использоваться для автоматической синхронизации регистрации в списке ожидания и ответов на опросы для Notion. Требуется настройка приложения Notion.

Аналитика

• _GOOGLE_ANALYTICS_API_SECRET , _GOOGLE_ANALYTICS_MEASUREMENT_ID : можно использовать для настройки аналитики на стороне сервера (GA4).
• _NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID , _NEXT_PUBLIC_COOKIE_DOMAIN , _NEXT_PUBLIC_COOKIE_NAME : можно использовать для настройки файлов cookie и аналитики на стороне клиента (Диспетчер тегов Google).

Среда

• _GOOGLE_ANALYTICS_DASHBOARD_URL , _GOOGLE_ANALYTICS_REPORTS_URL , _GOOGLE_SEARCH_CONSOLE_URL , _INTEGRATION_TEST_URL , _SERVER_LOGS_URL : можно использовать для добавления различных диагностических ссылок в панели администратора.
• _NEXT_PUBLIC_DOCS_URL , _NEXT_PUBLIC_SUPPORT_EMAIL : могут использоваться для создания ссылок на документацию и поддержку в рабочей области и на боковых панелях проекта.
• _NOREPLY_EMAIL_HOST , _NOREPLY_EMAIL_PORT : можно использовать для настройки альтернативного поставщика электронной почты для исходящих транзакционных писем.
• _API_URL : может использоваться для разделения трафика между веб-сайтом и API, например, если у вас есть отдельные поддомены, указывающие на ваш экземпляр.

Лицензия

PlayFetch является открытым исходным кодом под разрешительной лицензией MIT.

Обратите внимание, что PlayFetch использует CodeMirror в качестве зависимости. Если вы используете CodeMirror в коммерческих целях, существует социальное (но не юридическое) ожидание, что вы поможете финансировать его обслуживание.

Содействие

PlayFetch разрабатывается на GitHub. Взносы приветствуются. Не стесняйтесь открывать проблемы или открывать запросы на включение при исправлении ошибок или добавлении функций. Для начала немного вдохновения можно найти в TODO.md.