Installatie

Op deze pagina voeg je het pakket Aivie.Content toe aan een bestaande Umbraco 17-site. Aivie koppelen aan OpenAI volgt in Aan de slag.

Vereisten

• Umbraco 17.5.0 of nieuwer. Tegen die versie is Aivie zelf gebouwd. Gebruik als het kan 17.6.0 of nieuwer: op eerdere versies kan een bekend Umbraco-probleem de Aivie-licentie onleesbaar maken. Aivie blijft dan te bekijken, maar maakt en wijzigt niets meer tot de licentie weer te lezen is.
• .NET 10.
• SQL Server of SQLite als Umbraco-database. Aivie maakt daarin zijn eigen tabellen en heeft geen aparte connection string nodig.
• Een OpenAI API-sleutel. Die vul je in op het installatiescherm.

Umbraco.AI en Umbraco.Community.JobsJobsJobs (dat de achtergrondtaken draait) worden automatisch als afhankelijkheden geïnstalleerd. Je hoeft ze niet zelf toe te voegen.

Installeren met de .NET CLI

Voer de opdrachten uit in de map van je webproject. De volgorde is belangrijk.

.NET CLI

dotnet add package HtmlSanitizer --version 9.1.973
dotnet add package Aivie.Content

PackageReference

<PackageReference Include="HtmlSanitizer" Version="9.1.973" />
<PackageReference Include="Aivie.Content" Version="17.0.0" />

HtmlSanitizer moet op versie 9.1.973 of nieuwer staan voordat je Aivie toevoegt. Oudere versies zetten AngleSharp vast op precies 0.17.1, terwijl Umbraco.AI AngleSharp 1.4 of nieuwer nodig heeft, en NuGet kan een pakketverwijzing in je eigen project niet voor je ophogen. Zonder deze stap mislukt de restore met fout NU1107. Volg niet het advies in die foutmelding om AngleSharp rechtstreeks toe te voegen, want dat maakt het erger. Zie Fouten bij installatie en restore als je dit tegenkomt.

Verder hoeft er niets aan je site te veranderen. Aivie registreert zichzelf via composers, dus er is geen AddAivie()-aanroep die je aan Program.cs moet toevoegen. Heb je er nog een van een eerdere versie, dan doet die niets en kun je hem weghalen.

Data Protection vastzetten

Deze stap is optioneel, maar sterk aangeraden. Voeg het volgende toe aan Program.cs en vervang YourProject door een naam voor je site:

// At the top of the file; without this using the compiler does not know SetApplicationName and
// PersistKeysToFileSystem (CS1061).
using Microsoft.AspNetCore.DataProtection;

// Pin Data Protection.
//
// Without this, .NET stores the key ring in the profile of the account the site runs under, and
// derives the application discriminator from the content root path. Encrypted values become
// unreadable as soon as the app pool runs under a different account, the profile is not loaded, or
// the folder is moved.
//
// Umbraco.AI stores a connection's API key this way. If it can no longer be decrypted, the backoffice
// shows the raw value and encrypts it again on save - after which the connection is permanently
// broken. The same key ring protects login sessions and OpenIddict tokens.
//
// The folder belongs in your backups and must not be cleaned up. With multiple servers this must be a
// shared location.
builder.Services
    .AddDataProtection()
    .SetApplicationName("YourProject")
    .PersistKeysToFileSystem(
        new DirectoryInfo(Path.Combine(
            builder.Environment.ContentRootPath, "umbraco", "Data", "DataProtection-Keys")));

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddComposers()
    .Build();

WebApplication app = builder.Build();

waarschuwing

Zonder vastgezette key ring kan een API-sleutel die rechtstreeks in een Umbraco.AI-verbinding staat onleesbaar worden nadat je de site verhuist of de app pool onder een ander account gaat draaien. De verbinding is dan blijvend kapot tot je de sleutel opnieuw invult. Neem de sleutelmap op in je back-ups en gebruik een gedeelde locatie als je meer dan één server hebt. Is dit al gebeurd, zie dan API-sleutel onleesbaar na een verhuizing.

Wat er bij de eerste start gebeurt

Start de site en open de backoffice. Bij de eerste start zet Aivie zelf het volgende klaar:

1. Databasetabellen. Aivie maakt de tabellen die het nodig heeft in de Umbraco-database. Ze beginnen allemaal met aivie_.

2. Gebruikersgroepen. Aivie maakt drie groepen onder Gebruikers → User Groups, als ze nog niet bestaan:

   Groep	Toegang	Leden bij het aanmaken
   Aivie-admin	De Aivie-sectie	De Umbraco-beheerders, eenmalig
   Aivie	De Aivie-sectie	Geen
   Umbraco AI	De AI-sectie van Umbraco.AI (agents, contexts, profiles)	Geen

   Aivie-admin is de groep die Aivie mag installeren en configureren. Een Umbraco-beheerder die niet in deze groep zit, krijgt Installatie, Instellingen en Licentie niet te zien. Algemeen, Databronnen, Chatsuggesties en Zoekwoordacties ziet die wel, naast de schermen voor dagelijks gebruik. De andere twee groepen beginnen leeg, dus de juiste mensen voeg je zelf toe. Aivie verandert bij een latere start nooit de leden van een bestaande groep. Zie Rollen en toegang.

3. Toegang voor de Umbraco-groep Administrators. Heeft nog geen enkele gebruikersgroep toegang tot de Aivie-sectie, dan geeft Aivie die toegang eenmalig aan de Umbraco-groep Administrators. Dat gebeurt voordat de drie groepen hierboven worden gemaakt. Heeft een groep al toegang, dan laat Aivie het zoals het is.

4. De Aivie-sectie. De sectie verschijnt in de backoffice als Aivie - Content. Zolang het inrichten niet af is, meldt het welkomstscherm dat en toont het de knop Naar het installatiescherm. Alleen leden van Aivie-admin zien die melding.

5. Een omschrijvingsveld voor afbeeldingen. Aivie voegt het veld AI Omschrijving toe aan het mediatype Image, tenzij dat type al een omschrijvingsveld heeft. Zie Omschrijvingen van afbeeldingen.

Log je in als lid van Aivie-admin voordat het inrichten af is, dan verschijnt eenmaal per browser een venster met de titel Aivie is nog niet ingericht. Kies Naar het installatiescherm om het installatiescherm te openen, of Later om het venster te sluiten. De volgende stap is het installatiescherm.

Aivie bijwerken

Werk het pakket bij naar de nieuwste versie en herstart de site:

dotnet add package Aivie.Content

Meer is er voor een update niet nodig. Bij het starten brengt Aivie zijn standaardlagen voor instructies bij waar je ze niet hebt veranderd, voegt het standaardlagen toe die nieuw zijn in deze versie, en zet het de lagen die je wel hebt veranderd onder Nieuwere standaardlagen op het scherm Installatie, zodat je per laag beslist. Zie Standaardlagen.

Bestaande agents houden hun instructies, omdat die vaak per site zijn afgesteld. Bij het starten vervangt Aivie alleen een paar bekende zinnen uit eerdere standaardinstructies door hun huidige tekst. Een zin die je zelf hebt herschreven wordt niet gevonden en blijft staan. Verandert een nieuwe versie de instructietekst op een andere manier, pas die dan zelf aan onder AI → Agents → Instructions.

Standaard herstellen hoort niet bij een update

Na een update heb je Standaard herstellen niet nodig. De knop op het scherm Installatie, onder Standaardindeling herstellen, heeft een ander doel en is een bewuste keuze: hij zet de Aivie-contexts, en welke contexts en surfaces elke agent heeft, terug op de standaard van de geïnstalleerde versie. Ook vervangt hij de teksten van de lagen in die contexts door de standaardteksten. Dat is destructief: wat je met de hand hebt veranderd aan de Aivie-contexts, de koppelingen van de agents of de surfaces in AI → Contexts en AI → Agents wordt teruggezet, en dat is niet ongedaan te maken. Je databronnen, je klantspecifieke context, je eigen resources van een ander type, de instructies van de agents en de bestanden in de contextmap blijven staan.

Het is zinvol als iemand de contexts, de koppelingen van de agents of de surfaces met de hand heeft veranderd en je de standaard terug wilt, of als de site met een oudere versie is ingericht en je de indeling van de geïnstalleerde versie wilt. Zie De standaardindeling herstellen.