From 6c9f259607be647156c3edcb289b2a4463eccfc3 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Tue, 20 Aug 2024 00:25:57 +0300 Subject: [PATCH] Fix language usage in AI documentation --- en/ai/README.md | 16 ++++++----- en/ai/ai-providers-and-api-keys.md | 44 ++++++++++++++++-------------- en/ai/local-llm.md | 28 +++++++++---------- en/ai/preferences.md | 38 +++++++++++++------------- en/ai/troubleshooting.md | 6 ++-- 5 files changed, 69 insertions(+), 63 deletions(-) diff --git a/en/ai/README.md b/en/ai/README.md index 5e7f572e7..69f163b6d 100644 --- a/en/ai/README.md +++ b/en/ai/README.md @@ -1,25 +1,25 @@ # AI functionality in JabRef -Since version 6, JabRef has AI-functionality build in. +Since version 6, JabRef has AI functionality built in. - AI can generate a summary of a research paper -- One can also chat with papers using a "smart" AI assistant +- You can also chat with papers using a "smart" AI assistant ## AI summary tab -On activation of this tab, AI will generate for you a quick overview of the paper. +When you activate this tab, AI will generate a quick overview of the paper for you. ![AI summary tab screenshot](../.gitbook/assets/AiSummary.png) -The AI will mention main objectives of the research, methods used, key findings, and conclusions. +The AI will mention the main objectives of the research, methods used, key findings, and conclusions. ## AI chat tab -Here, one can ask questions, which are answered by the LLM. +Here, you can ask questions, which are answered by the LLM. ![AI chat tab screenshot](../.gitbook/assets/AiChat.png) -In this window you can see the following elements: +In this window, you can see the following elements: - Chat history with your messages - Prompt for sending messages @@ -27,7 +27,9 @@ In this window you can see the following elements: ## How does the AI functionality work? -In the background, JabRef analyses the linked PDF files of library entries. The information used after the indexing is then supplied to the AI, which, to be precise, in our case is a Large Language Model (LLM). The LLM is currently not stored on your computer. Instead, we have many integrations with AI providers (OpenAI, Mistral AI, Hugging Face), so you can choose the one you like the most. These AI providers are available only remotely via the internet. In short: we send chunks of text to AI service and then receive processed responses. In order to use it you need to configure JabRef to use your API key. +In the background, JabRef analyses the linked PDF files of library entries. After indexing, this information is supplied to the AI, which, in our case, is a Large Language Model (LLM). +The LLM is currently not stored on your computer. Instead, we have many integrations with AI providers (OpenAI, Mistral AI, Hugging Face), so you can choose the one you like the most. +We send chunks of text to AI service and then receive processed responses. To use it, you need to configure JabRef with your API key. ## More information diff --git a/en/ai/ai-providers-and-api-keys.md b/en/ai/ai-providers-and-api-keys.md index 05e754054..949f77a81 100644 --- a/en/ai/ai-providers-and-api-keys.md +++ b/en/ai/ai-providers-and-api-keys.md @@ -2,51 +2,55 @@ ## What is an AI provider? -An AI provider is a company or a service that gives you the ability to send requests to and receive responses from LLM. In order to get the response, you also need to send an API key to authenticate and manage billing. +An AI provider is a company or a service that gives you the ability to send requests to and receive responses from an LLM. In order to get the response, you also need to send an API key to authenticate and manage billing. -Here is the list of AI providers we currently support: OpenAI, Mistral AI, Hugging Face. Others include Google Vertex AI, Microsoft Azure OpenAI, Anthropic, etc. You can find more information on this topic on [langchain4j documentation website](https://docs.langchain4j.dev/category/language-models). This is the framework that we use in JabRef. This page lists available integrations. +Here is the list of AI providers we currently support: OpenAI, Mistral AI, Hugging Face. Others include Google Vertex AI, Microsoft Azure OpenAI, Anthropic, etc. You can find more information on this topic on the [`langchain4j` documentation website](https://docs.langchain4j.dev/category/language-models). This is the framework that we use in JabRef. This page lists available integrations. ## What is an API key? An API key or API token is like a password that lets an app or program access information or services from another -app or website, such as an LLM service. It ensures only authorized users or applications can use +app or website, such as an LLM service. It ensures that only authorized users or applications can use the service. For example, when an app uses an LLM service to generate text or answer questions, it includes its unique API key in the request. The LLM service checks this key to make sure the request is legitimate before providing the response. This process keeps the data secure and helps track how the service is being used. ## Which AI provider should I use? -We recomend you chosing the OpenAI. +For now, we recommend you choosing [OpenAI](https://platform.openai.com/docs/models). -For Mistral AI you need to make a subscription, while for OpenAI you can send money one time. +For Mistral AI, you might need to make a subscription, whereas for OpenAI, a one-time payment option is available -Hugging Face gives you access to numerous count of models for free. But it will take a very long time for Hugging Face to find a free computer resources for you, and the response time will be also long. +Hugging Face gives you access to numerous count of models for free. +However, it may take a long time for Hugging Face to allocate free computing resources, resulting in longer response times + +In order to use any service, you always need an API key. +Please head to the [AI user documentation](https://docs.jabref.org/ai/ai-providers-and-api-keys) to learn about how to receive a key and where to enter it in the preferences. ## How to get an API key? ### How to get an OpenAI API key? -To get an OpenAI API key you need to perform these steps: +To get an OpenAI API key, follow these steps: -1. Login or create an account on [OpenAI website](https://platform.openai.com/login?launch) -2. Go to "API" section -3. Go to "Dashboard" (upper-right corner) -4. Go to "API keys" (left menu) +1. Log in or create an account on the [OpenAI website](https://platform.openai.com/login?launch) +2. Go to the "API" section +3. Go to the "Dashboard" (upper-right corner) +4. Go to the "API keys" (left menu) 5. Click "Create new secret key" 6. Click "Create secret key" -7. OpenAI will show you the key +7. OpenAI will display the key ### How to get a Mistral AI API key? -1. Login or create an account on [Mistral AI website](https://auth.mistral.ai/ui/login) +1. Login or create an account on the [Mistral AI website](https://auth.mistral.ai/ui/login) 2. Go to the [dashboard -> API keys](https://console.mistral.ai/api-keys/) 3. There you will find a button "Create new key". Click on it -4. You can optionally setup a name to API key and its expiration date +4. You can optionally set up a name for the API key and its expiration date 5. After the creation, you will see "Your key is:" with a string of random characters after that ### How to get a Hugging Face API key? -Hugging Face call an "API key" as "Access Token". It does not make much difference, you can interchangably use either "API key", or "API token", or "access token". +Hugging Face refers to an "API key" as an "Access Token". It does not make much difference, you can interchangeably use either "API key", or "API token", or "access token". 1. [Login](https://huggingface.co/login) or [create account](https://huggingface.co/join) on Hugging Face 2. Go to [create access token](https://huggingface.co/settings/tokens/new?) @@ -56,9 +60,9 @@ Hugging Face call an "API key" as "Access Token". It does not make much differen ## What should I do with the API key and how can I enter it in JabRef? -Don't share the key to anyone, it's a secret that was created only for your account. Don't enter this key to unknown and unverfied services. +Do not share the key with anyone, it is a secret that was created only for your account. Do not enter this key into unknown or unverified services. -Now you need to copy and paste it in JabRef preferences. To do this: +Now you need to copy and paste it into JabRef preferences. To do this: 1. Launch JabRef 2. Go "File" -> "Preferences" -> "AI" (a new tab!) @@ -76,9 +80,9 @@ If you have some money on your credit balance, you can chat with your library! ### OpenAI -In order to increase your credit balance on OpenAI, do this: +To increase your credit balance on OpenAI, follow these steps: -1. Add payment method [there](https://platform.openai.com/settings/organization/billing/payment-methods). +1. Add payment method [here](https://platform.openai.com/settings/organization/billing/payment-methods). 2. Add credit balance on [this](https://platform.openai.com/settings/organization/billing/overview) page. ### Mistral AI @@ -87,4 +91,4 @@ Make the subscription on [their website](https://console.mistral.ai/billing/subs ### Hugging Face -You don't have to pay any cent for Hugging Face in order to send requests to LLMs. Though, the speed is very slow. +You do not have to pay anything for Hugging Face in order to send requests to LLMs. Though, the speed is very slow. diff --git a/en/ai/local-llm.md b/en/ai/local-llm.md index f4cb3a990..8f71cc23d 100644 --- a/en/ai/local-llm.md +++ b/en/ai/local-llm.md @@ -3,32 +3,32 @@ Notice: 1. This tutorial is intended for expert users -2. Local LLM model requires a lot of computational power -3. Smaller models typically have less performance then bigger ones like OpenAI models +2. Local LLM requires a lot of computational power +3. Smaller models typically have lower performance than bigger ones like OpenAI models -## General explanation +## High-level explanation -You can use any program that will create a server with OpenAI compatible API. +You can use any program that creates a server with OpenAI-compatible API. After you started your service, you can do this: -1. The "Chat Model" field in AI preference is editable, so you can write any model you have downloaded -2. There is a field "API base URL" in "Expert Settings" where you need to supply the address of an OpenAI API compatible server +1. The "Chat Model" field in AI preferences is editable, so you can enter any model you have downloaded +2. There is a field called "API base URL" in "Expert Settings" where you need to provide the address of an OpenAI-compatible API server -Voi la! You can use a local LLM right away in JabRef. +Voilà! You can use a local LLM right away in JabRef. ## Step-by-step guide for `ollama` -The following steps guide you how to use `ollama` for downloading and running local LLMs. +The following steps guide you on how to use `ollama` to download and runn local LLMs. 1. Install `ollama` from [their website](https://ollama.com/download) -2. Select a model that you want to run. The `ollama` provides [a big list of models](https://ollama.com/library) to choose from (we recommend you to try [`gemma2:2b`](https://ollama.com/library/gemma2:2b), or [`mistral:7b`](https://ollama.com/library/mistral), or [`tinyllama`](https://ollama.com/library/tinyllama)) -3. When you selected your model, type `ollama pull :` in your terminal. `` refers to the model name like `gemma2` or `mistral`, and `` referes to parameters count like `2b` or `9b` +2. Select a model that you want to run. The `ollama` provides [a large list of models](https://ollama.com/library) to choose from (we recommend trying [`gemma2:2b`](https://ollama.com/library/gemma2:2b), or [`mistral:7b`](https://ollama.com/library/mistral), or [`tinyllama`](https://ollama.com/library/tinyllama)) +3. When you have selected your model, type `ollama pull :` in your terminal. `` refers to the model name like `gemma2` or `mistral`, and `` refers to parameters count like `2b` or `9b` 4. `ollama` will download the model for you -5. After that you can run `ollama serve` to start a local web-server. It's a server to which you can send requests and it will respond with LLM output. Notice: `ollama` server may be already running, so don't be scared of `cannot bind` error -6. Got to JabRef Preferences -> AI +5. After that, you can run ollama serve to start a local web server. This server will accept requests and respond with LLM output. Note: The ollama server may already be running, so do not be alarmed by a cannot bind error. +6. Go to JabRef Preferences -> AI 7. Set the "AI provider" to "OpenAI" -8. Set the "Chat Model" to whichever model you've downloaded in form `:` -9. Set the "API base URL" in "Expert Settings" to: `http://localhost:11434/v1/` +8. Set the "Chat Model" to the model you have downloaded in the format `:` +9. Set the "API base URL" in "Expert Settings" to `http://localhost:11434/v1/` Now, you are all set and can chat "locally". diff --git a/en/ai/preferences.md b/en/ai/preferences.md index c50dc414e..8655af954 100644 --- a/en/ai/preferences.md +++ b/en/ai/preferences.md @@ -1,14 +1,14 @@ # AI preferences -Here are some new options in the JabRef preferences. +Here are some new options in JabRef preferences. ![AI preferences](../.gitbook/assets/AiPreferences.png) -- "Enable AI functionality in JabRef": by default it's turned off, so you need to check this option, if you want to use the new AI features +- "Enable AI functionality in JabRef": by default it is turned off, so you need to check this option if you want to use the new AI features - "AI provider": you can choose either OpenAI, Mistral AI, or Hugging Face -- "Chat model": choose the model you like (for OpenAI we recommend `gpt-4o-mini`, as it the cheapest and fastest) -- "API token": here you write your API token -- "Expert settings": here you can change the parameters that affect how AI will generate your answers. If you don't understand the meaning of those settings, don't worry! We have experimented a lot and found the best parameters for you! But if you are curious, then you can refer to the AI expert settings section. +- "Chat model": choose the model you like (for OpenAI we recommend `gpt-4o-mini`, as to date, it is the cheapest and fastest, though we also recommend to look up the prices periodically, as they are subject to change) +- "API token": enter your API token here +- "Expert settings": the defaults provide good results. In case you would like to modify them, the next section provides an explanation of them ## AI expert settings @@ -18,19 +18,19 @@ Here are some new options in the JabRef preferences. **Requirements**: valid URL address -The "API Base URL" is a setting that tells your application where to find the language model's online service. Think of it as the main address or starting point for all communications with the language model. By specifying this URL, your application knows exactly where to send its requests to get responses from the language model. +The "API Base URL" setting tells your application where to find the language model's online service. Think of it as the main address or starting point for all communications with the language model. By specifying this URL, your application knows exactly where to send requests to get responses from the language model. -You don't have to set this parameter manually and remember all the addresses. JabRef will automatically substitute the address for you, when you select the AI provider. +You do not have to set this parameter manually or remember all the addresses. JabRef will automatically substitute the address for you when you select the AI provider. ### Embedding model **Requirements**: choose one available from combo box -The Embedding model transforms a document (or a piece of text) into a vector (an ordered collection of numbers). This is used to supply the AI with relevant information regarding your questions. +The embedding model transforms a document (or a piece of text) into a vector (an ordered collection of numbers). This transformation provides the AI with relevant information for your questions. -Different embedding models have different performance: this includes accuracy and how fast embeddings can be computed. `Q` at the end of the model name usually means *quantized* (meaning *reduced*, *simplified*). These models are faster and smaller than their original counterpart, but provide slightly less accuracy. +Different embedding models have varying performance, including accuracy and the speed of computing embeddings. The `_q` at the end of the model name usually denotes *quantized* (meaning reduced or simplified). These models are faster and smaller than their original counterparts but provide slightly less accuracy. -Currently, only local embedding models are supported. That means, you don't have to provide a new API key and all the logic will be run on your machine. +Currently, only local embedding models are supported. This means you do not need to provide a new API key, as all the processing will be done on your machine. ### Instruction @@ -38,9 +38,9 @@ Currently, only local embedding models are supported. That means, you don't have **Requirements**: not empty -An instruction (also known as "system message") in a Large Language Models (LLMs) sets the tone and rules for the conversation. Think of it as instructions given to the AI before it starts interacting with a user. It guides the AI on how to respond, ensuring it stays on topic and behaves appropriately. For example, a system message might tell the AI to be formal, concise, or provide detailed explanations. This helps the AI provide more relevant and useful answers tailored to the specific needs of the user. +An instruction (also known as a "system message") in Large Language Models (LLMs) sets the tone and rules for the conversation. Think of it as instructions given to the AI before it starts interacting with a user. It guides the AI on how to respond, ensuring it stays on topic and behaves appropriately. For example, a system message might tell the AI to be formal, concise, or provide detailed explanations. This helps the AI provide more relevant and useful answers tailored to the user's specific needs. -**Important**: in JabRef the system message for LLM is constructed from this supplied text + information about current library entry. So, at the end of your text you should add a note like "Here is the information about the library entry you are chatting about:". +**Important**: in JabRef, the system message for the LLM is constructed from the supplied text plus information about the current library entry. Therefore, at the end of your text, you should add a note such as "Here is the information about the library entry you are chatting about:" ### Context window size @@ -56,9 +56,9 @@ The "context window size" in our application helps the AI remember and respond t **Requirements**: > 0 -The "chunk size" parameter in document splitting refers to the size of segments into which linked files are divided for processing by AI models. When dealing with linked files, such as PDF files, they are segmented into smaller chunks based on this parameter. Each segment typically contains a specified number of words or characters, ensuring manageable units for analysis and generating answers. +The "chunk size" parameter in document splitting refers to the size of segments into which linked files are divided for processing by AI models. When dealing with linked files, such as PDFs, they are segmented into smaller chunks based on this parameter. Each segment typically contains a specified number of words or characters, ensuring manageable units for analysis and generating answers. -These segments are then passed to the AI model for processing. This approach helps optimize performance by breaking down large documents into smaller, more digestible parts, enabling more efficient handling and analysis by the AI. +These segments are then passed to the AI model for processing. This approach helps optimize performance by breaking down large documents into smaller, more digestible parts, allowing for more efficient handling and analysis by the AI. ### Document splitter chunk overlap @@ -66,7 +66,7 @@ These segments are then passed to the AI model for processing. This approach hel **Requirements**: > 0 && < chunk size -The "chunk overlap" parameter determines how much text from adjacent chunks is shared when dividing linked files into segments. This overlap is measured in characters and ensures continuity and context across segmented chunks. By sharing a specified amount of text between adjacent segments, typically at the beginning and/or end of each chunk, the AI model can maintain coherence and understanding of the content across segmented parts. This approach helps enhance the accuracy and relevance of responses generated by the AI from the segmented content. +The "chunk overlap" parameter determines how much text from adjacent chunks is shared when dividing linked files into segments. This overlap is measured in characters and ensures continuity and context across segmented chunks. By sharing a specified amount of text between adjacent segments, typically at the beginning and/or end of each chunk, the AI model can maintain coherence and understanding of the content across segments. This approach helps enhance the accuracy and relevance of responses generated by the AI from the segmented content. ### Retrieval augmented generation maximum results count @@ -74,9 +74,9 @@ The "chunk overlap" parameter determines how much text from adjacent chunks is s **Requirements**: > 0 -The parameter "Retrieval augmented generation: maximum results count" specifies the maximum number of chunks or segments of text that will be retrieved for processing and generating responses. When using retrieval-augmented generation (RAG), which combines traditional language model generation with retrieval of relevant text segments, this parameter determines how many segments are considered for each query or input. +The parameter "Retrieval augmented generation: maximum results count" specifies the maximum number of chunks or segments of text to retrieve for processing and generating responses. When using retrieval-augmented generation (RAG), which combines traditional language model generation with the retrieval of relevant text segments, this parameter determines how many segments are considered for each query or input. -Setting this parameter controls the scope of information the AI model uses to generate responses, balancing between depth of context and computational efficiency. It ensures that the AI focuses on the most relevant segments to provide accurate and contextually rich answers based on the user's input or query. +Setting this parameter controls the scope of information the AI model uses to generate responses, balancing depth of context and computational efficiency. It ensures that the AI focuses on the most relevant segments to provide accurate and contextually rich answers based on the user's input or query. ### Retrieval augmented generation minimum score @@ -84,6 +84,6 @@ Setting this parameter controls the scope of information the AI model uses to ge **Requirements**: > 0 && < 1 -The "Retrieval augmented generation: minimum score" parameter sets the threshold for relevance when retrieving chunks of text for generation. It specifies the minimum score that segments must achieve to be included in the results. Any text segments scoring below this threshold are excluded from consideration in the AI's response generation process. +The "Retrieval augmented generation: minimum score" parameter sets the relevance threshold when retrieving chunks of text for generation. It specifies the minimum score that segments must achieve to be included in the results. Any text segments scoring below this threshold are excluded from the AI's response generation process. -This parameter is crucial in ensuring that the AI model focuses on retrieving and utilizing only the most relevant information from the retrieved chunks. By filtering out segments that do not meet the specified relevance score, the AI enhances the quality and accuracy of its responses, aligning more closely with the user's needs and query context. +This parameter is crucial for ensuring that the AI model focuses on retrieving and utilizing only the most relevant information from the retrieved chunks. By filtering out segments that do not meet the specified relevance score, the AI enhances the quality and accuracy of its responses, aligning more closely with the user's needs and query context. diff --git a/en/ai/troubleshooting.md b/en/ai/troubleshooting.md index 39692550f..665ab5f19 100644 --- a/en/ai/troubleshooting.md +++ b/en/ai/troubleshooting.md @@ -2,7 +2,7 @@ ## "Failed to load PyTorch native library" while trying the AI chat -If you encounter this error, download the latest [Visual C++ redistributable from Miscrosoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version). +If you encounter this error, download the latest [Visual C++ redistributable from Microsoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-microsoft-visual-c-redistributable-version). This installation is only required for AI features in JabRef, all other features can work without it. @@ -10,6 +10,6 @@ If you still encounter this error, then try the approach discussed in the next s ## JabRef closed or crashed in the middle of downloading the embedding model -Don't worry! You need to delete embedding model cache. +Do not worry! You need to delete embedding model cache. -The name of the folder is `.djl.ai` and it is inside you home directory. +The name of the folder is `.djl.ai`, and it is located in your home directory.