serverless-chat-langchainjs — RAG 知识库工具中文文档

Getting started

There are multiple ways to get started with this project.

The quickest way is to use GitHub Codespaces that provides a preconfigured environment for you. Alternatively, you can set up your local environment following the instructions below.

[!IMPORTANT] If you want to run this sample entirely locally using Ollama, you have to follow the instructions in the local environment section.

Deploy the sample to Azure

Azure prerequisites

• Azure account. If you're new to Azure, get an Azure account for free to get free Azure credits to get started. If you're a student, you can also get free credits with Azure for Students.
• Azure subscription with access enabled for the Azure OpenAI service. You can request access with this form.
• Azure account permissions:
• Your Azure account must have Microsoft.Authorization/roleAssignments/write permissions, such as Role Based Access Control Administrator, User Access Administrator, or Owner. If you don't have subscription-level permissions, you must be granted RBAC for an existing resource group and deploy to that existing group.
• Your Azure account also needs Microsoft.Resources/deployments/write permissions on the subscription level.

Cost estimation

See the cost estimation details for running this sample on Azure.

Deploy the sample

1. Open a terminal and navigate to the root of the project. 2. Authenticate with Azure by running azd auth login. 3. Run azd up to deploy the application to Azure. This will provision Azure resources, deploy this sample, and build the search index based on the files found in the ./data folder. - You will be prompted to select a base location for the resources. If you're unsure of which location to choose, select eastus2. - By default, the OpenAI resource will be deployed to eastus2. You can set a different location with azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location>. Currently only a short list of locations is accepted. That location list is based on the OpenAI model availability table and may become outdated as availability changes.

The deployment process will take a few minutes. Once it's done, you'll see the URL of the web app in the terminal.

You can now open the web app in your browser and start chatting with the bot.

Enhance security

When deploying the sample in an enterprise context, you may want to enforce tighter security restrictions to protect your data and resources. See the enhance security guide for more information.

Enable CI/CD

If you want to enable Continuous Deployment for your forked repository, you need to configure the Azure pipeline first:

1. Open a terminal at the root of your forked project. 2. Authenticate with Azure by running azd auth login. 3. Run azd pipeline config to configure the required secrets and variables for connecting to Azure from GitHub Actions. - This command will set up the necessary Azure service principal and configure GitHub repository secrets. - Follow the prompts to complete the configuration.

Once configured, the GitHub Actions workflow will automatically deploy your application to Azure whenever you push changes to the main branch.

Clean up

To clean up all the Azure resources created by this sample:

1. Run azd down --purge
2. When asked if you are sure you want to continue, enter y

The resource group and all the resources will be deleted.

Run the sample

There are multiple ways to run this sample: locally using Ollama or Azure OpenAI models, or by deploying it to Azure.

Run the sample locally with Ollama

If you have a machine with enough resources, you can run this sample entirely locally without using any cloud resources. To do that, you first have to install Ollama and then run the following commands to download the models on your machine:

ollama pull llama3.1:latest
ollama pull nomic-embed-text:latest

[!NOTE] The llama3.1 model with download a few gigabytes of data, so it can take some time depending on your internet connection.

After that you have to install the NPM dependencies:

npm install

Then you can start the application by running the following command which will start the web app and the API locally:

npm start

Then, open a new terminal running concurrently and run the following command to upload the PDF documents from the /data folder to the API:

npm run upload:docs

This only has to be done once, unless you want to add more documents.

You can now open the URL http://localhost:8000 in your browser to start chatting with the bot.

[!NOTE] While local models usually works well enough to answer the questions, sometimes they may not be able to follow perfectly the advanced formatting instructions for the citations and follow-up questions. This is expected, and a limitation of using smaller local models.

Run the sample locally with Azure OpenAI models

First you need to provision the Azure resources needed to run the sample. Follow the instructions in the Deploy the sample to Azure section to deploy the sample to Azure, then you'll be able to run the sample locally using the deployed Azure resources.

Once your deployment is complete, you should see a .env file in the packages/api folder. This file contains the environment variables needed to run the application using Azure resources.

To run the sample, you can then use the same commands as for the Ollama setup. This will start the web app and the API locally:

npm start

Open the URL http://localhost:8000 in your browser to start chatting with the bot.

Note that the documents are uploaded automatically when deploying the sample to Azure with azd up.

[!TIP] You can switch back to using Ollama models by simply deleting the packages/api/.env file and starting the application again. To regenerate the .env file, you can run azd env get-values > packages/api/.env.

Use your local environment

You need to install following tools to work on your local machine:

• Node.js LTS
• Azure Developer CLI
• Git
• PowerShell 7+ (for Windows users only)_
• Important: Ensure you can run pwsh.exe from a PowerShell command. If this fails, you likely need to upgrade PowerShell.
• Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands.
• Azure Functions Core Tools (should be installed automatically with NPM, only install manually if the API fails to start)_

Then you can get the project code:

1. Fork the project to create your own copy of this repository.
2. On your forked repository, select the Code button, then the Local tab, and copy the URL of your forked repository.

FAQ

You can find answers to frequently asked questions in the FAQ.

Troubleshooting

If you have any issue when running or deploying this sample, please check the troubleshooting guide. If you can't find a solution to your problem, please open an issue in this repository.